The GreptimeDB MCP Server enables AI assistants to query, analyze, and manage time-series data, logs, metrics, and traces in GreptimeDB through a secure, read-only interface.
Core Query Capabilities: Execute SQL queries (MySQL dialect, SELECT/SHOW/DESCRIBE only), PromQL-compatible TQL queries, and time-window aggregation queries with RANGE/ALIGN syntax. Multiple output formats available (CSV, JSON, Markdown) with configurable result limits and time ranges.
Schema & Resource Management: List all tables as browsable resources with greptime://<table>/data URIs, inspect table schemas (column names, types, constraints), and read table data through resource endpoints.
Pipeline Management: Create, test (dry-run), list, and delete data processing pipelines using YAML configurations. AI-assisted generation of pipeline configurations from log samples.
Specialized Analysis Templates: Access predefined prompts for log analysis with full-text search, metrics monitoring, PromQL-style queries (TQL EVAL), IoT device monitoring with TAG/FIELD semantics, distributed trace analysis for OpenTelemetry spans, and table diagnostics including region health and query optimization.
Query Analysis & Health: Analyze SQL/TQL query execution plans with EXPLAIN functionality for performance optimization, check database connection status and server version.
Security & Privacy: Automatically blocks all DDL/DML operations (DROP, DELETE, INSERT, UPDATE), dynamic SQL execution, and file system access. Masks sensitive data in columns matching patterns like password, api_key, credit_card, and ssn with configurable patterns.
Integration & Configuration: Seamlessly integrates with Claude Desktop and other MCP-compatible AI assistants. Configurable via environment variables or command-line arguments for connection details, HTTP/HTTPS API settings, timezone, connection pool size, and data masking options.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GreptimeDB MCP Servershow me the schema for the metrics table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
greptimedb-mcp-server
A Model Context Protocol (MCP) server for GreptimeDB — an open-source observability database that handles metrics, logs, and traces in one engine.
Enables AI assistants to query and analyze GreptimeDB using SQL, TQL (PromQL-compatible), and RANGE queries, with built-in security features like read-only enforcement and data masking.
Quick Start
# Install
pip install greptimedb-mcp-server
# Run (connects to localhost:4002 by default)
greptimedb-mcp-server --host localhost --database publicFor Claude Desktop, add this to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"greptimedb": {
"command": "greptimedb-mcp-server",
"args": ["--host", "localhost", "--database", "public"]
}
}
}Related MCP server: SQLite MCP Server
Features
Tools
Tool | Description |
| Execute SQL queries with format (csv/json/markdown) and limit options |
| Execute TQL (PromQL-compatible) queries for time-series analysis |
| Execute time-window aggregation queries with RANGE/ALIGN syntax |
| Get table schema including column names, types, and constraints |
| Analyze SQL or TQL query execution plans |
| Check database connection status and server version |
Pipeline Management
Tool | Description |
| List all pipelines or get details of a specific pipeline |
| Create a new pipeline with YAML configuration |
| Test a pipeline with sample data without writing to database |
| Delete a specific version of a pipeline |
Resources & Prompts
Resources: Browse tables via
greptime://<table>/dataURIsPrompts: Built-in templates for common tasks —
pipeline_creator,log_pipeline,metrics_analysis,promql_analysis,iot_monitoring,trace_analysis,table_operation
For LLM integration and prompt usage, see docs/llm-instructions.md.
Configuration
Environment Variables
GREPTIMEDB_HOST=localhost # Database host
GREPTIMEDB_PORT=4002 # MySQL protocol port (default: 4002)
GREPTIMEDB_USER=root # Database user
GREPTIMEDB_PASSWORD= # Database password
GREPTIMEDB_DATABASE=public # Database name
GREPTIMEDB_TIMEZONE=UTC # Session timezone
# Optional
GREPTIMEDB_HTTP_PORT=4000 # HTTP API port for pipeline management
GREPTIMEDB_HTTP_PROTOCOL=http # HTTP protocol (http/https)
GREPTIMEDB_POOL_SIZE=5 # Connection pool size
GREPTIMEDB_MASK_ENABLED=true # Enable sensitive data masking
GREPTIMEDB_MASK_PATTERNS= # Additional patterns (comma-separated)
GREPTIMEDB_AUDIT_ENABLED=true # Enable audit logging
# Transport (for HTTP server mode)
GREPTIMEDB_TRANSPORT=stdio # stdio, sse, or streamable-http
GREPTIMEDB_LISTEN_HOST=0.0.0.0 # HTTP server bind host
GREPTIMEDB_LISTEN_PORT=8080 # HTTP server bind port
GREPTIMEDB_ALLOWED_HOSTS= # DNS rebinding protection (comma-separated)
GREPTIMEDB_ALLOWED_ORIGINS= # CORS allowed origins (comma-separated)CLI Arguments
greptimedb-mcp-server \
--host localhost \
--port 4002 \
--database public \
--user root \
--password "" \
--timezone UTC \
--pool-size 5 \
--mask-enabled true \
--transport stdioHTTP Server Mode
For containerized or Kubernetes deployments. Requires mcp>=1.8.0:
# Streamable HTTP (recommended for production)
greptimedb-mcp-server --transport streamable-http --listen-port 8080
# SSE mode (legacy)
greptimedb-mcp-server --transport sse --listen-port 3000DNS Rebinding Protection
By default, DNS rebinding protection is disabled for compatibility with proxies, gateways, and Kubernetes services. To enable it, use --allowed-hosts:
# Enable DNS rebinding protection with allowed hosts
greptimedb-mcp-server --transport streamable-http \
--allowed-hosts "localhost:*,127.0.0.1:*,my-service.namespace:*"
# With custom allowed origins for CORS
greptimedb-mcp-server --transport streamable-http \
--allowed-hosts "my-service.namespace:*" \
--allowed-origins "http://localhost:*,https://my-app.example.com"
# Or via environment variables
GREPTIMEDB_ALLOWED_HOSTS="localhost:*,my-service.namespace:*" \
GREPTIMEDB_ALLOWED_ORIGINS="http://localhost:*" \
greptimedb-mcp-server --transport streamable-httpIf you encounter 421 Invalid Host Header errors, either disable protection (default) or add your host to the allowed list.
Security
Read-Only Database User (Recommended)
Create a read-only user in GreptimeDB using static user provider:
mcp_readonly:readonly=your_secure_passwordApplication-Level Security Gate
All queries go through a security gate that:
Blocks: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
Blocks: Encoded bypass attempts (hex, UNHEX, CHAR)
Allows: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION
Data Masking
Sensitive columns are automatically masked (******) based on column name patterns:
Authentication:
password,secret,token,api_key,credentialFinancial:
credit_card,cvv,bank_accountPersonal:
ssn,id_card,passport
Configure with --mask-patterns phone,email to add custom patterns.
Audit Logging
All tool invocations are logged:
2025-12-10 10:30:45 - greptimedb_mcp_server.audit - INFO - [AUDIT] execute_sql | query="SELECT * FROM cpu LIMIT 10" | success=True | duration_ms=45.2Disable with --audit-enabled false.
Development
# Clone and setup
git clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git
cd greptimedb-mcp-server
uv venv && source .venv/bin/activate
uv sync
# Run tests
pytest
# Format & lint
uv run black .
uv run flake8 src
# Debug with MCP Inspector
npx @modelcontextprotocol/inspector uv --directory . run -m greptimedb_mcp_server.serverLicense
MIT License - see LICENSE.md.
Acknowledgement
Inspired by:
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.