MCP TimescaleDB Server

A Model Context Protocol (MCP) server for TimescaleDB Cloud that provides secure access to PostgreSQL databases.

Prerequisites

• Node.js (v16 or newer recommended)
• npm (comes with Node.js)
• TypeScript (installed as a dev dependency, but you may want it globally for development: npm install -g typescript)

A TimescaleDB Cloud account and credentials are also required.

Installation

1. Install dependencies:

   npm install
   

2. Copy the environment template:

   cp .env.example .env
   

3. Configure your TimescaleDB credentials in .env:

   TIMESCALE_HOST=your-timescale-host.tsdb.cloud.timescale.com
   TIMESCALE_PORT=31316
   TIMESCALE_DB=tsdb
   TIMESCALE_USER=tsdbadmin
   TIMESCALE_PASSWORD=your_password
   TIMESCALE_SSL_MODE=require
   

Building

npm run build

Usage

Note: If you are using this server as part of an MCP client (see the "MCP Configuration" section below), you do not need to run npm run dev or npm start manually—the MCP client will launch the server automatically using the specified command. The scripts below are for local development and testing only.

Development

npm run dev

Production

npm run build
npm start

MCP Configuration

Add this to your MCP client configuration:

{
  "mcpServers": {
    "mcp-timescale": {
      "command": "node",
      "args": ["/path/to/your/dist/index.js"],
      "env": {
        "TIMESCALE_HOST": "<your-timescale-host>",
        "TIMESCALE_PORT": "31316",
        "TIMESCALE_DB": "tsdb",
        "TIMESCALE_USER": "tsdbadmin",
        "TIMESCALE_PASSWORD": "<your-password>",
        "TIMESCALE_SSL_MODE": "require"
      }
    }
  }
}

Security

• All database connections use SSL/TLS encryption
• Credentials are managed through environment variables
• Connection timeouts are configurable
• Query timeouts prevent long-running queries

Available Tools

timescale_query

Execute SQL queries on TimescaleDB Cloud.

Parameters:

• query (string, required): SQL query to execute
• timeout (number, optional): Query timeout in milliseconds

Example:

{
  "name": "timescale_query",
  "arguments": {
    "query": "SELECT * FROM users LIMIT 10"
  }
}

timescale_list_tables

List all tables in the current database.

Parameters:

• schema (string, optional): Schema name (defaults to 'public')

Example:

{
  "name": "timescale_list_tables",
  "arguments": {
    "schema": "public"
  }
}

timescale_describe_table

Get table schema information.

Parameters:

• table (string, required): Table name
• schema (string, optional): Schema name (defaults to 'public')

Example:

{
  "name": "timescale_describe_table",
  "arguments": {
    "table": "users",
    "schema": "public"
  }
}

Development

Project Structure

TimescaleMCPServer/
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .env.example         # Environment variables template
├── src/
│   ├── index.ts         # Main entry point
│   ├── server.ts        # MCP server implementation
│   └── database.ts      # Database client
└── README.md           # This file