GreptimeDB MCP Server

DatabasesPython

Access and query GreptimeDB time-series database

Available Tools

list_resources

Lists available tables in the GreptimeDB database

read_resource

Reads data from a specified table

list_tools

Lists available tools that can be used with the database

call_tool

Executes an SQL query on the database

list_prompts

Lists available prompt templates

get_prompt

Retrieves a specific prompt template by name

GreptimeDB MCP Server provides AI assistants with a secure and structured way to explore and analyze time-series data stored in GreptimeDB. It enables assistants to list tables, read data, and execute SQL queries through a controlled interface, ensuring responsible database access while maintaining security. This integration allows AI models to directly interact with your time-series data for analytics, visualization recommendations, and data-driven insights without exposing sensitive database credentials or risking unintended modifications.

Overview

GreptimeDB MCP Server enables AI assistants to interact with GreptimeDB, a distributed time-series database. This integration allows AI models to explore database structure, read data, and execute SQL queries in a controlled environment.

Installation

Install the package using pip:

pip install greptimedb-mcp-server

Configuration

You can configure the server using environment variables or command-line arguments.

Environment Variables

Set the following environment variables:

GREPTIMEDB_HOST=localhost    # Database host
GREPTIMEDB_PORT=4002         # Database port (defaults to 4002)
GREPTIMEDB_USER=root         # Database username
GREPTIMEDB_PASSWORD=         # Database password
GREPTIMEDB_DATABASE=public   # Database name

Command-line Arguments

Alternatively, use these command-line arguments:

--host: Database host
--port: Database port
--user: Database username
--password: Database password
--database: Database name

Integration with Claude Desktop

To integrate with Claude Desktop, add the MCP server configuration to Claude's configuration file:

MacOS

Edit the file at: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows

Edit the file at: %APPDATA%/Claude/claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "greptimedb": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/greptimedb-mcp-server",
        "run",
        "-m",
        "greptimedb_mcp_server.server"
      ],
      "env": {
        "GREPTIMEDB_HOST": "localhost",
        "GREPTIMEDB_PORT": "4002",
        "GREPTIMEDB_USER": "root",
        "GREPTIMEDB_PASSWORD": "",
        "GREPTIMEDB_DATABASE": "public"
      }
    }
  }
}

Replace /path/to/greptimedb-mcp-server with the actual path to your installation, and adjust the database connection parameters as needed.

Debugging

For debugging purposes, you can use the MCP Inspector:

npx @modelcontextprotocol/inspector uv \
  --directory \
  /path/to/greptimedb-mcp-server \
  run \
  -m \
  greptimedb_mcp_server.server

This tool helps verify that your MCP server is functioning correctly and responding to requests as expected.