GreptimeDB MCP Server

greptimedb-mcp-server

build workflow

A Model Context Protocol (MCP) server implementation for GreptimeDB.

This server provides AI assistants with a secure and structured way to explore and analyze databases. It enables them to list tables, read data, and execute SQL queries through a controlled interface, ensuring responsible database access.

Project Status

This is an experimental project that is still under development. Data security and privacy issues have not been specifically addressed, so please use it with caution.

Capabilities

list_resources to list tables
read_resource to read table data
list_tools to list tools
call_tool to execute an SQL
list_prompts to list prompts
get_prompt to get the prompt by name

Installation

pip install greptimedb-mcp-server

Configuration

Set the following environment variables:

GREPTIMEDB_HOST=localhost    # Database host
GREPTIMEDB_PORT=4002         # Optional: Database MySQL port (defaults to 4002 if not specified)
GREPTIMEDB_USER=root
GREPTIMEDB_PASSWORD=
GREPTIMEDB_DATABASE=public

Or via command-line args:

--host the database host, localhost by default,
--port the database port, must be MySQL protocol port, 4002 by default,
--user the database username, empty by default,
--password the database password, empty by default,
--database the database name, public by default.

Usage

Claude Desktop Integration

Configure the MCP server in Claude Desktop's configuration file:

MacOS

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows

Location: %APPDATA%/Claude/claude_desktop_config.json

{
  "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"
      }
    }
  }
}

License

MIT License - see LICENSE.md file for details.

Contribute

Prerequisites

Python with uv package manager
GreptimeDB installation
MCP server dependencies

Development

# Clone the repository
git clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git
cd greptimedb-mcp-server

# Create virtual environment
uv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install development dependencies
uv sync

# Run tests
pytest

Use MCP Inspector for debugging:

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

Acknowledgement

This library's implementation was inspired by the following two repositories and incorporates their code, for which we express our gratitude：

Thanks!

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A Model Context Protocol server implementation that enables AI assistants to securely interact with GreptimeDB, allowing them to explore database schema, read data, and execute SQL queries through a controlled interface.

Related Resources

Reddit Discussion about this server

Related MCP Servers

MSSQL MCP Server
JexinSam
-
security
A
license
-
quality
A Model Context Protocol server that enables secure and structured interaction with Microsoft SQL Server databases, allowing AI assistants to list tables, read data, and execute SQL queries with controlled access.
Last updated -
20
Python
MIT License
Microsoft SQL Server MCP Server
RichardHan
A
security
A
license
A
quality
A Model Context Protocol server that enables secure interaction with Microsoft SQL Server databases, allowing AI assistants to list tables, read data, and execute SQL queries through a controlled interface.
Last updated -
1
108
Python
MIT License
ClickHouse MCP Server
dubin555
-
security
-
license
-
quality
A Model Context Protocol server that enables AI assistants to securely interact with ClickHouse databases, supporting table exploration and SQL query execution through a controlled interface.
Last updated -
6
Python
Apache 2.0
OceanBase MCP Server
yuanoOo
A
security
A
license
A
quality
A Model Context Protocol server that enables AI assistants to securely interact with OceanBase databases by listing tables, reading data, and executing SQL queries through a controlled interface.
Last updated -
1
2
Python
Apache 2.0

View all related MCP servers

GreptimeDB MCP Server