mcplist
GR

GreptimeDB

Created 6 months ago

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

Visit Homepage
development documentation public

What is GreptimeDB?

Provides AI assistants with a secure and structured way to explore and analyze data in [GreptimeDB](https://github.com/GreptimeTeam/greptimedb).

Documentation

greptimedb-mcp-server

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
GREPTIMEDB_TIMEZONE=UTC

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.
  • --timezone the session time zone, empty by default(using server default time zone).

Usage# Claude Desktop Integration

Configure the MCP server in Claude Desktop's configuration file:\n\n#### 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",
        "GREPTIMEDB_TIMEZONE": ""
      }
    }
  }
}

License

MIT License - see LICENSE.md file for details.

Contribute# Prerequisites

  • Python with uv package manager
  • GreptimeDB installation
  • MCP server dependencies

Development

git clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git
cd greptimedb-mcp-server\n\n# Create virtual environment
uv venv
source venv/bin/activate # or `venv\Scripts\activate` on Windows\n\n# Install development dependencies
uv sync\n\n# 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：

Server Config 

{
  "mcpServers": {
    "greptimedb-server": {
      "command": "npx",
      "args": [
        "greptimedb"
      ]
    }
  }
}

Links & Status

Repository: github.com
Hosted: No
Global: No
Official: Yes

Project Info

Hosted Featured
Created At: May 23, 2025
Updated At: Aug 07, 2025
Author: Greptime Team
Category: official
License: MIT License
Tags:
development documentation public