greptimedb-mcp-server

greptimedb-mcp-server

面向 GreptimeDB 的模型上下文协议（MCP）服务——GreptimeDB 是一个开源可观测性数据库，可在一个引擎中处理指标、日志和链路追踪。

让 AI 助手能够使用 SQL、TQL（兼容 PromQL）和 RANGE 查询来查询和分析 GreptimeDB，并提供只读强制执行和数据脱敏等内置安全功能。

快速开始

# Install
pip install greptimedb-mcp-server

# Run (connects to localhost:4002 by default)
greptimedb-mcp-server --host localhost --database public

对于 Claude Desktop，请将以下内容添加到配置文件中（macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "greptimedb": {
      "command": "greptimedb-mcp-server",
      "args": ["--host", "localhost", "--database", "public"]
    }
  }
}

功能

工具

工具	说明
execute_sql	执行 SQL 查询，支持格式（csv/json/markdown）和行数限制选项
execute_tql	执行 TQL（兼容 PromQL）查询，用于时间序列分析
query_range	使用 RANGE/ALIGN 语法执行时间窗口聚合查询
search_table_semantics	按可观测性概念查找表，并根据匹配词排序；搜索表名、语义选项和实体声明。schema 用于选择要搜索的数据库
query_semantic_graph	查询语义图：在必需的时间窗口内查询 summary（内容概述）、entities（节点）和 relationships（边）
describe_table	查看表概况：架构、语义元数据、最新样本行和查询指南
explain_query	分析 SQL 或 TQL 查询执行计划（analyze=true 用于运行时统计；同时添加 analyze=true 和 verbose=true，可查看每个分区的扫描指标和索引剪枝计数）
health_check	检查数据库连接状态和服务版本

search_table_semantics 和 describe_table 中的语义元数据会读取 information_schema.table_semantics。只有包含 greptime.semantic.* 选项或通过内置约定推导出实体声明的表才会出现在其中；其他表不会显示。服务每个进程只读取一次该视图的列列表，并且只选择该视图提供的列。entity_declarations 需要 GreptimeDB 1.3；在更早版本中，它会被报告为缺少列，而不是空声明集。

工具结果受 GREPTIMEDB_MAX_RESULT_BYTES 限制（默认值为 1048576，即 1 MiB）。查询结果超出预算时，会返回较少的行，并在 truncated 和 truncation_reason 中说明；如果没有可删减的行，则会在结果末尾截断并附上提示。该预算用于防止结果过大而无法被处理；如果 MCP 客户端在达到此限制前就拒绝结果，请调低此值。

跨数据库查询

服务连接到一个数据库，但读取范围不限于该数据库：

工具	如何访问其他数据库
execute_sql、query_range、describe_table	将表限定为 schema.table
execute_tql	metric{__schema__="other_db"}，仅接受 =
search_table_semantics	传入 schema
query_semantic_graph	已覆盖整个目录；无需限定范围

连接账户需要对目标数据库具有读取权限。使用 SHOW DATABASES 列出数据库。

query_semantic_graph 会读取 greptime_private.semantic_entities 和 greptime_private.semantic_relationships，这两者需要 GreptimeDB 1.3。启动时，服务会检查这两个视图是否存在、是否包含读取所需的列，以及连接账户是否有权读取；如果条件不满足，则不会提供该工具，并会记录原因。该工具必须指定时间窗口，且窗口为左闭右开区间 [start_time, end_time)，范围基于 observed_at；窗口内的数据会按 60 秒观测时间桶聚合。

流水线管理

工具	描述
list_pipelines	列出所有流水线，或获取特定流水线的详细信息
create_pipeline	使用 YAML 配置创建新的流水线
dryrun_pipeline	使用示例数据测试流水线，但不写入数据库
delete_pipeline	删除特定版本的流水线

仪表板管理

工具	描述
list_dashboards	列出所有 Perses 仪表板定义
create_dashboard	创建或更新 Perses 仪表板定义
delete_dashboard	删除仪表板定义

资源与提示词

• 资源：通过 greptime://<table>/data URI 浏览表
• 提示词：用于常见任务的内置 Jinja 模板 — pipeline_creator、log_pipeline、metrics_analysis、promql_analysis、trace_analysis、table_operation、schema_design_advisor、observability_correlation、ingestion_troubleshooting、query_performance_tuning

有关大模型集成和提示词用法，请参阅 docs/llm-instructions.md。

这些工具可用于查询和管理现有 GreptimeDB 中的数据。有关部署、服务配置、写入协议、流水线语法、模式设计和性能诊断，请将助手指向 GreptimeDB 技能索引：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)

CLI 参数

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

HTTP 服务模式

适用于容器化或 Kubernetes 部署：

# 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

DNS 重绑定防护

默认情况下，为兼容代理、网关和 Kubernetes 服务，DNS 重绑定防护处于禁用状态。若要启用，请使用 --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

如果遇到 421 Invalid Host Header 错误，可以禁用防护（默认设置），或将主机添加到允许列表中。

安全

只读数据库用户（推荐）

使用 静态用户提供程序 在 GreptimeDB 中创建只读用户：

mcp_readonly:readonly=your_secure_password

应用级安全闸门

所有查询都会经过安全闸门，该闸门会：

• 拦截：DROP、DELETE、TRUNCATE、UPDATE、INSERT、ALTER、CREATE、GRANT、REVOKE、EXEC、LOAD、COPY
• 拦截：经过编码的绕过尝试（hex、UNHEX、CHAR）
• 允许：SELECT、SHOW、DESCRIBE、TQL、EXPLAIN、UNION

写入模式（默认禁用）

服务默认为只读。启用写入模式后，所有会更改存储状态的操作都会开放：

• 通过 execute_sql 执行具有破坏性的 SQL（DDL/DML，例如 CREATE、DROP、ALTER、INSERT、UPDATE、 DELETE）
• create_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

启用后，execute_sql 将绕过安全检查，且服务会在启动时记录警告。关闭写入模式时，这四种工具会直接返回错误，不会联系服务；list_pipelines、list_dashboards 和 dryrun_pipeline 均为只读操作，仍可使用。

⚠️ 危险：这会允许 AI 助手对数据库执行具有破坏性的语句。切勿在生产数据上启用此功能。如果只需要读取权限，请同时使用只读数据库用户。

数据脱敏

敏感列会根据列名模式自动脱敏（******）：

• 身份验证：password、secret、token、api_key、credential
• 财务信息：credit_card、cvv、bank_account
• 个人信息：ssn、id_card、passport

使用 --mask-patterns phone,email 配置其他自定义模式。

审计日志

所有工具调用都会记录日志：

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

使用 --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.md。

致谢

灵感来源：

• ktanaka101/mcp-server-duckdb
• designcomputer/mysql_mcp_server
• mikeskarl/mcp-prompt-templates