TimescaleDB MCP Server

A Python-based Model Context Protocol (MCP) server for TimescaleDB that enables AI assistants to interact with your time-series database.

Features

• Async Database Operations: Built on asyncpg for high-performance async database access

• Connection Pooling: Efficient connection pool management with configurable pool sizes

• MCP Resources: Schema introspection via MCP resources for tables and hypertables

• MCP Prompts: Pre-built prompts for common operations (query time-series, analyze hypertables, explore schema)

• SQL Injection Prevention: Parameterized queries throughout for security

• Comprehensive Error Handling: Custom exceptions with clear error messages

• Type Safety: Full type hints and TypedDict support

• 6 MCP Tools: Execute queries, list/describe tables and hypertables, query time-series data

• Structured Logging: Comprehensive logging for debugging and monitoring

Installation

From PyPI

Or using uv (faster):

The package is available on PyPI.

From Source

1. Clone this repository:

2. Install using pip:

Or using uv:

For development with additional tools:

Configuration

Configuration is managed via environment variables with the TIMESCALEDB_ prefix.

Required Settings

Optional Settings

You can set these as environment variables or create a .env file in the project root.

Usage

Running the Server

After installation, you can run the MCP server in several ways:

Using the console script:

As a Python module:

The server will start and be ready to accept MCP protocol requests via stdio.

MCP Client Configuration

To use this server with an MCP client (like Claude Desktop), add it to your MCP configuration.

Option 1: Using the installed console script (recommended):

Option 2: Using Python module:

Option 3: Using uv (if installed via uv):

MCP Tools

The server provides the following tools:

• execute_query: Execute a SQL query with parameterized support and return results

• list_tables: List all tables in the database

• describe_table: Get detailed information about a table (columns, types, row counts)

• list_hypertables: List all TimescaleDB hypertables

• describe_hypertable: Get detailed information about a hypertable (dimensions, chunks, compression)

• query_timeseries: Query time-series data with optional time-bucketing and aggregation

MCP Resources

The server exposes database schema as MCP resources:

• Table Resources: timescaledb://table/{table_name} - Access table schemas and metadata

• Hypertable Resources: timescaledb://hypertable/{hypertable_name} - Access hypertable schemas and metadata

Resources are automatically discovered and listed, making it easy for AI assistants to explore your database structure.

MCP Prompts

Pre-built prompts for common operations:

• query_timeseries_data: Generate queries for time-series data retrieval

• analyze_hypertable: Analyze hypertable structure, chunks, and performance metrics

• explore_database_schema: Get an overview of all tables and hypertables in the database

Development

This project uses the official MCP Python SDK to implement the Model Context Protocol.

Project Structure

The project follows modern Python packaging standards with a src-layout:

Development Setup

1. Clone the repository:

   git clone https://github.com/brunoprela/timescaledb-mcp.git cd timescaledb-mcp

2. Install in editable mode with dev dependencies:

   pip install -e ".[dev]" # or uv pip install -e ".[dev]"

3. Run tests:

   make test # or uv run pytest tests/ -v

4. Run tests with coverage:

   make test-cov # or uv run pytest tests/ -v --cov=timescaledb_mcp --cov-report=html

5. Run all checks:

   make check # This runs: lint, type-check, and test

Testing

The test suite includes both unit tests (that don't require a database) and integration tests (that require a TimescaleDB instance).

By default,

• Starts a TimescaleDB Docker container

• Waits for it to be ready

• Runs all tests (including database tests)

• Stops and removes the container when done

Simply run:

Or with coverage:

Manual testing (if you have your own TimescaleDB instance):

Requirements: Docker must be installed and running for make test to work. If Docker is not available, database tests will be skipped automatically.

Code Quality

The project uses:

• Black for code formatting

• Ruff for linting

• MyPy for type checking

• Pytest for testing with async support

All checks run automatically in CI via GitHub Actions.

Running Checks Locally

You can run all checks locally using the Makefile:

Alternatively, you can use uv directly:

Security

• SQL Injection Prevention: All queries use parameterized statements

• Input Validation: Table and hypertable names are validated

• Connection Security: Supports SSL connections (configure via connection string)

• Error Handling: Sensitive information is not exposed in error messages

Performance

• Async Operations: Built on asyncpg for non-blocking I/O

• Connection Pooling: Efficient connection reuse with configurable pool sizes

• Query Timeouts: Configurable timeouts to prevent long-running queries

• Resource Management: Proper cleanup of connections and resources

Publishing

The package is automatically published to PyPI via GitHub Actions when you create a GitHub Release. See .github/SETUP_PUBLISHING.md for setup instructions.

Quick setup:

1. Set up PyPI Trusted Publishing (recommended)

   • Or add PYPI_API_TOKEN as a GitHub secret

2. Update version in pyproject.toml

3. Create a GitHub Release with matching tag (e.g., v0.1.0)

4. The workflow will automatically build and publish to PyPI

License

MIT