GreptimeDB MCP
A Model Context Protocol (MCP) server for GreptimeDB
What is GreptimeDB MCP?
GreptimeDB MCP is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to model context protocol (mcp) server for greptimedb
A Model Context Protocol (MCP) server for GreptimeDB
This server falls under the Databases category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- execute_sql
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx greptimedbConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use GreptimeDB MCP
The GreptimeDB MCP Server connects AI assistants to a GreptimeDB time-series database, exposing tools for SQL and TQL query execution, table inspection, data pipeline management, and dashboard operations. GreptimeDB is purpose-built for observability data — metrics, logs, and traces — making this server ideal for letting Claude query infrastructure metrics, analyze performance trends, or build monitoring dashboards through natural language. Read-only mode is enforced by default with optional audit logging and sensitive data masking.
Prerequisites
- Python 3.9 or later with pip installed
- A running GreptimeDB instance (local or cloud) accessible over the network
- GreptimeDB connection details: host, port (default 4002), database name, and optional credentials
- An MCP client such as Claude Desktop or Claude Code
Install the GreptimeDB MCP server
Install the Python package from PyPI using pip.
pip install greptimedb-mcp-serverVerify the connection with a quick start command
Run the server from the CLI to confirm it can connect to your GreptimeDB instance. Use the --host and --database flags to specify your connection.
greptimedb-mcp-server --host localhost --port 4002 --database publicConfigure environment variables
Set environment variables for your GreptimeDB connection. This is the recommended approach for Claude Desktop configs where you embed credentials in the env block.
export GREPTIMEDB_HOST=localhost
export GREPTIMEDB_PORT=4002
export GREPTIMEDB_DATABASE=public
export GREPTIMEDB_USER=greptime
export GREPTIMEDB_PASSWORD=yourpassword
# Optional: enable audit logging and data masking
export GREPTIMEDB_AUDIT_ENABLED=true
export GREPTIMEDB_MASK_ENABLED=true
# Enable write access if needed (disabled by default)
export GREPTIMEDB_ALLOW_WRITE=trueConfigure your MCP client
Add the GreptimeDB MCP server to your Claude Desktop or Claude Code configuration, passing connection details via environment variables.
{
"mcpServers": {
"greptimedb": {
"command": "greptimedb-mcp-server",
"args": ["--host", "localhost", "--database", "public"],
"env": {
"GREPTIMEDB_HOST": "localhost",
"GREPTIMEDB_PORT": "4002",
"GREPTIMEDB_DATABASE": "public",
"GREPTIMEDB_USER": "greptime",
"GREPTIMEDB_PASSWORD": "yourpassword"
}
}
}
}Explore available tools
The server exposes tools across four categories: query execution (execute_sql, execute_tql, query_range, explain_query), inspection (describe_table, health_check), pipeline management (list_pipelines, create_pipeline, dryrun_pipeline, delete_pipeline), and dashboard operations (list_dashboards, create_dashboard, delete_dashboard).
GreptimeDB MCP Examples
Client configuration
Claude Desktop configuration for connecting to a local GreptimeDB instance with read-only access and audit logging enabled.
{
"mcpServers": {
"greptimedb": {
"command": "greptimedb-mcp-server",
"args": ["--host", "localhost", "--database", "public"],
"env": {
"GREPTIMEDB_HOST": "localhost",
"GREPTIMEDB_PORT": "4002",
"GREPTIMEDB_DATABASE": "public",
"GREPTIMEDB_AUDIT_ENABLED": "true",
"GREPTIMEDB_MASK_ENABLED": "true"
}
}
}
}Prompts to try
These prompts exercise the core time-series query and inspection capabilities of the GreptimeDB MCP server.
- "Show me the top 5 tables in the public database by row count"
- "Query the CPU usage metrics for the last hour and identify any spikes above 90%"
- "Describe the schema of the system_metrics table"
- "Run a health check on the GreptimeDB instance"
- "List all data pipelines and their current status"Troubleshooting GreptimeDB MCP
Connection refused when starting the MCP server
Verify GreptimeDB is running and listening on the configured port (default 4002 for the gRPC/HTTP protocol). Check with `greptimedb-mcp-server --host localhost --port 4002 --database public` and look for connection error messages.
Write queries (INSERT, DELETE, DROP) are being blocked
By default, GREPTIMEDB_ALLOW_WRITE is false and all destructive operations are blocked. Set `GREPTIMEDB_ALLOW_WRITE=true` in your environment or the MCP client config env block to enable write access.
Sensitive column values are being masked and you need the real values
Sensitive data masking is controlled by GREPTIMEDB_MASK_ENABLED. Set it to `false` in your environment to disable masking. Note that masking applies to columns with names matching patterns like 'password', 'token', and 'credit_card'.
Frequently Asked Questions about GreptimeDB MCP
What is GreptimeDB MCP?
GreptimeDB MCP is a Model Context Protocol (MCP) server that model context protocol (mcp) server for greptimedb It connects AI assistants to external tools and data sources through a standardized interface.
How do I install GreptimeDB MCP?
Follow the installation instructions on the GreptimeDB MCP GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with GreptimeDB MCP?
GreptimeDB MCP works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is GreptimeDB MCP free to use?
Yes, GreptimeDB MCP is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
GreptimeDB MCP Alternatives — Similar Databases Servers
Looking for alternatives to GreptimeDB MCP? Here are other popular databases servers you can use with Claude, Cursor, and VS Code.
Excelize
★ 20.6kGo language library for reading and writing Microsoft Excel™ (XLAM / XLSM / XLSX / XLTM / XLTX) spreadsheets
MCP Toolbox for Databases
★ 15.3kOpen source MCP server specializing in easy, fast, and secure tools for Databases.
DBHub
★ 2.8kA universal database gateway MCP server that enables AI assistants to connect to and query multiple databases (PostgreSQL, MySQL, MariaDB, SQL Server, SQLite) with support for schema exploration, SQL execution, and secure connections via SSH tunnels.
Tabularis
★ 2.1kA lightweight, cross-platform database client for developers. Supports MySQL, PostgreSQL and SQLite. Hackable with plugins. Built for speed, security, and aesthetics.
Postgres AI Guide
★ 1.7kMCP server and Claude plugin for Postgres skills and documentation. Helps AI coding tools generate better PostgreSQL code.
Anyquery
★ 1.7k🏎️ 🏠 ☁️ - Query more than 40 apps with one binary using SQL. It can also connect to your PostgreSQL, MySQL, or SQLite compatible database. Local-first and private by design.
Browse More Databases MCP Servers
Explore all databases servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up GreptimeDB MCP in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use GreptimeDB MCP?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.