greptimedb-mcp-server
A Model Context Protocol (MCP) server for — an open-source observability database that handles metrics, logs, and traces in one engine.
Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
uvx greptimedb-mcp-server==0.6.0Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
GREPTIMEDB_HOST=<value> GREPTIMEDB_PORT=<value> GREPTIMEDB_USER=<value> GREPTIMEDB_PASSWORD=<secret> GREPTIMEDB_DATABASE=<value> GREPTIMEDB_TIMEZONE=<value> GREPTIMEDB_POOL_SIZE=<value> GREPTIMEDB_HTTP_PORT=<value> GREPTIMEDB_HTTP_PROTOCOL=<value> GREPTIMEDB_MASK_ENABLED=<value> GREPTIMEDB_MASK_PATTERNS=<value> GREPTIMEDB_AUDIT_ENABLED=<value> GREPTIMEDB_ALLOW_WRITE=<value> claude mcp add io.github.greptimeteam-greptimedb-mcp-server -- uvx greptimedb-mcp-server==0.6.0รันในเทอร์มินัล
{ "mcpServers": { "io.github.greptimeteam-greptimedb-mcp-server": { "command": "uvx", "args": [ "greptimedb-mcp-server==0.6.0" ], "env": { "GREPTIMEDB_HOST": "<value>", "GREPTIMEDB_PORT": "<value>", "GREPTIMEDB_USER": "<value>", "GREPTIMEDB_PASSWORD": "<secret>", "GREPTIMEDB_DATABASE": "<value>", "GREPTIMEDB_TIMEZONE": "<value>", "GREPTIMEDB_POOL_SIZE": "<value>", "GREPTIMEDB_HTTP_PORT": "<value>", "GREPTIMEDB_HTTP_PROTOCOL": "<value>", "GREPTIMEDB_MASK_ENABLED": "<value>", "GREPTIMEDB_MASK_PATTERNS": "<value>", "GREPTIMEDB_AUDIT_ENABLED": "<value>", "GREPTIMEDB_ALLOW_WRITE": "<value>" } } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิด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.
# Install
pip install greptimedb-mcp-server
# Run (connects to localhost:4002 by default)
greptimedb-mcp-server --host localhost --database public
For 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"]
}
}
}
search_table_semantics and the semantic metadata in describe_table read information_schema.table_semantics. A table appears there when it carries a greptime.semantic.* option or a built-in convention derives an entity declaration for it; other tables are absent. The server reads the view's column list once per process and selects only the columns it exposes. entity_declarations requires GreptimeDB 1.3; on earlier versions it is reported as a missing column rather than as an empty declaration set.
Tool results are bounded by GREPTIMEDB_MAX_RESULT_BYTES (default 1048576, or 1 MiB). A query result over the budget returns fewer rows and reports it in truncated and truncation_reason; a result with no rows to shed is cut with a notice at the end. The budget is a backstop against a result too large to be consumed, so lower it if your MCP client rejects results before it is reached.
The server connects to one database, but reads are not restricted to it:
The connected account needs read permission on the target database. Use SHOW DATABASES to list them.
query_semantic_graph reads greptime_private.semantic_entities and greptime_private.semantic_relationships, which require GreptimeDB 1.3. At startup the server checks that both views exist, carry the columns it reads, and are readable by the connected account; when they are not, the tool is not offered and the reason is logged. Its time window is required and half-open, [start_time, end_time) over observed_at, and rows are aggregated across the 60-second observation buckets in that window.
greptime://<table>/data URIspipeline_creator, log_pipeline, metrics_analysis, promql_analysis, trace_analysis, table_operation, schema_design_advisor, observability_correlation, ingestion_troubleshooting, query_performance_tuningFor LLM integration and prompt usage, see docs/llm-instructions.md.
These tools cover querying and managing data in an existing GreptimeDB. For deployment, server configuration, write protocols, pipeline syntax, schema design, and performance diagnosis, point the assistant at the GreptimeDB skills index at https://docs.greptime.com/SKILL.md.
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/dashboard 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
GREPTIMEDB_ALLOW_WRITE=false # Allow writes: DDL/DML plus pipeline and dashboard changes (DANGEROUS, local/test only)
GREPTIMEDB_MAX_RESULT_BYTES=1048576 # Byte budget for a single tool result (1 MiB)
# 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)
greptimedb-mcp-server \
--host localhost \
--port 4002 \
--database public \
--user root \
--password "" \
--timezone UTC \
--pool-size 5 \
--mask-enabled true \
--allow-write false \
--transport stdio
For containerized or Kubernetes deployments:
# Streamable HTTP (recommended for production)
greptimedb-mcp-server --transport streamable-http --listen-port 8080
# SSE mode (legacy)
greptimedb-mcp-server --transport sse --listen-port 3000
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-http
If you encounter 421 Invalid Host Header errors, either disable protection (default) or add your host to the allowed list.
Create a read-only user in GreptimeDB using static user provider:
mcp_readonly:readonly=your_secure_password
All queries go through a security gate that:
The server is read-only by default. Write mode enables every operation that changes stored state:
CREATE, DROP, ALTER, INSERT, UPDATE,
DELETE) through execute_sqlcreate_pipeline, delete_pipeline, create_dashboard, delete_dashboard# Environment variable
GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server
# Or CLI argument
greptimedb-mcp-server --allow-write true
When enabled, the security gate is bypassed for execute_sql, and the server
logs a warning on startup. With write mode off, those four tools return an error
without contacting the server; list_pipelines, list_dashboards and
dryrun_pipeline are read-only and stay available.
⚠️ Danger: This lets an AI assistant run destructive statements against your database. Never enable it against production data. Combine with a read-only database user if you only need read access.
Sensitive columns are automatically masked (******) based on column name patterns:
password, secret, token, api_key, credentialcredit_card, cvv, bank_accountssn, id_card, passportConfigure with --mask-patterns phone,email to add custom patterns.
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.2
Disable with --audit-enabled false.
# 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.server
MIT License - see LICENSE.md.
Inspired by:
Query GreptimeDB metrics, logs and traces with SQL, TQL and RANGE. Manage pipelines and dashboards.
{ "mcpServers": { "io.github.greptimeteam-greptimedb-mcp-server": { "command": "uvx", "args": [ "greptimedb-mcp-server==0.6.0" ], "env": { "GREPTIMEDB_HOST": "<value>", "GREPTIMEDB_PORT": "<value>", "GREPTIMEDB_USER": "<value>", "GREPTIMEDB_PASSWORD": "<secret>", "GREPTIMEDB_DATABASE": "<value>", "GREPTIMEDB_TIMEZONE": "<value>", "GREPTIMEDB_POOL_SIZE": "<value>", "GREPTIMEDB_HTTP_PORT": "<value>", "GREPTIMEDB_HTTP_PROTOCOL": "<value>", "GREPTIMEDB_MASK_ENABLED": "<value>", "GREPTIMEDB_MASK_PATTERNS": "<value>", "GREPTIMEDB_AUDIT_ENABLED": "<value>", "GREPTIMEDB_ALLOW_WRITE": "<value>" } } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ผู้เผยแพร่ระบุตัวแปรสภาพแวดล้อมเหล่านี้: GREPTIMEDB_HOST, GREPTIMEDB_PORT, GREPTIMEDB_USER, GREPTIMEDB_PASSWORD, GREPTIMEDB_DATABASE, GREPTIMEDB_TIMEZONE, GREPTIMEDB_POOL_SIZE, GREPTIMEDB_HTTP_PORT, GREPTIMEDB_HTTP_PROTOCOL, GREPTIMEDB_MASK_ENABLED, GREPTIMEDB_MASK_PATTERNS, GREPTIMEDB_AUDIT_ENABLED, GREPTIMEDB_ALLOW_WRITE
Greptimedb ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-09 Query GreptimeDB metrics, logs and traces with SQL, TQL and RANGE. Manage pipelines and dashboards.