TimescaleDB MCP Server

How to use

Start the MCP server locally and connect your MCP client to it. Use the provided tools to execute parameterized SQL, inspect database objects, and query time-series data with optional bucketing and aggregation. The server exposes its resources so your AI assistant can discover table and hypertable schemas and then generate precise queries against your TimescaleDB instance.

How to install

Prerequisites: you need Python and/or Node tooling to run the MCP server locally. You will also need access to a TimescaleDB instance and its connection details.

# Option A: install from PyPI
pip install timescaledb-mcp

# Option A with uv for faster startup
uv pip install timescaledb-mcp

# Option B: install from source (editable mode for development)
git clone https://github.com/brunoprela/timescaledb-mcp.git
cd timescaledb-mcp
pip install -e .
# or
uv pip install -e .

# Optional for development with extra tools
pip install -e ".[dev]"
# or
uv pip install -e ".[dev]"

Configuration

Configure the server using environment variables with the TIMESCALEDB_ prefix.

TIMESCALEDB_HOST=localhost
TIMESCALEDB_PORT=5432
TIMESCALEDB_DATABASE=your_database
TIMESCALEDB_USER=your_user
TIMESCALEDB_PASSWORD=your_password

# Optional pool and timeout settings
TIMESCALEDB_MIN_POOL_SIZE=1
TIMESCALEDB_MAX_POOL_SIZE=10
TIMESCALEDB_QUERY_TIMEOUT=30.0

Running the server

You can start the MCP server in several ways. Choose the method that matches your preferred workflow.

timescaledb-mcp
```

```bash
python -m timescaledb_mcp
```

```bash
uv run timescaledb-mcp

MCP client configuration examples

Configure your MCP client to connect to the local server using one of the available runtime options. The following examples show local, stdio-based configurations that run the MCP server directly.

{
  "mcpServers": {
    "timescaledb": {
      "command": "timescaledb-mcp",
      "env": {
        "TIMESCALEDB_HOST": "localhost",
        "TIMESCALEDB_PORT": "5432",
        "TIMESCALEDB_DATABASE": "your_database",
        "TIMESCALEDB_USER": "your_user",
        "TIMESCALEDB_PASSWORD": "your_password"
      }
    }
  }
}

MCP client configuration using Python module

{
  "mcpServers": {
    "timescaledb": {
      "command": "python",
      "args": ["-m", "timescaledb_mcp"],
      "env": {
        "TIMESCALEDB_HOST": "localhost",
        "TIMESCALEDB_PORT": "5432",
        "TIMESCALEDB_DATABASE": "your_database",
        "TIMESCALEDB_USER": "your_user",
        "TIMESCALEDB_PASSWORD": "your_password"
      }
    }
  }
}

MCP client configuration using uv (uvx)

{
  "mcpServers": {
    "timescaledb": {
      "command": "uv",
      "args": ["run", "timescaledb-mcp"],
      "env": {
        "TIMESCALEDB_HOST": "localhost",
        "TIMESCALEDB_PORT": "5432",
        "TIMESCALEDB_DATABASE": "your_database",
        "TIMESCALEDB_USER": "your_user",
        "TIMESCALEDB_PASSWORD": "your_password"
      }
    }
  }
}

MCP Resources

The server exposes database schema as MCP resources so your assistant can explore the structure of your data.

MCP Prompts

Pre-built prompts are available to help your assistant craft queries and analyze structures.

MCP Tools

The server provides a set of tools to interact with the database.

Security and reliability

All queries use parameterized statements to prevent SQL injection and connections are managed with pooling for performance. Sensitive error information is avoided in messages.

Performance

Async operations powered by a high-performance driver plus configurable timeouts and proper resource cleanup help maintain responsiveness under load.

Testing and development

A modern test setup runs unit and integration tests with Docker for TimescaleDB. Use the provided commands to run tests and check code quality locally.

Notes

Maintain your TimescaleDB connection details in environment variables and adjust pool sizes according to workload. You can skip tests that require a live database if you lack a working TimescaleDB instance.

Development

This project is built with Python and uses an MCP SDK to implement the server, exposing tools, resources, and prompts for AI-assisted database interactions.

Notes on usage with a TimescaleDB instance

Ensure your database is reachable from the host running the MCP server. Use TLS/SSL as needed by configuring the connection string in the environment variables.

execute_query

Execute a parameterized SQL query and return results.

list_tables

List all tables in the connected database.

describe_table

Return detailed information about a table, including columns and row counts.

list_hypertables

List all TimescaleDB hypertables in the database.

describe_hypertable

Provide details about a hypertable, including dimensions and chunks.

query_timeseries

Query time-series data with optional bucketing and aggregation.