MCP Server

Chronosphere MCP 服务

适用于 Chronosphere 的 MCP 服务。提供用于获取日志、指标、追踪、事件以及部分实体的工具。

本项目使用 semver 管理发布版本。我们尚未达到 1.0 版本，因此次要版本号更新可能包含破坏性变更。

常用主机的 MCP 配置（claude desktop、cursor）

远程服务

使用 MCP 服务最简单的方式是使用我们托管的远程服务：

身份验证

你可以使用 Chronosphere API token，也可以使用 OAuth 连接 Chronosphere MCP 服务。若要通过 OAuth 使用 MCP，MCP 客户端必须支持 OAuth。

OAuth 支持是新功能，尚未在所有客户端上进行测试。如果无法正常使用，请在 Slack 中联系 Chronosphere 支持，并提供以下信息：

1. 你使用的 MCP 客户端（例如 VS code、codex、cursor 等）
2. 你尝试进行身份验证时采取的步骤
3. 你看到的错误。

基于标头的配置

一些 MCP 主机允许你为发送到 MCP 服务的请求附加自定义 HTTP 标头。Chronosphere MCP 服务支持以下面向用户的标头。

禁用工具（X-Chrono-MCP-Disable-Tools）

使用此标头可从 MCP 客户端显示的工具列表中隐藏指定工具。

• 格式：以逗号分隔的 MCP 工具名称列表（可用工具表格中的 工具名称 列）
• 示例值：query_logs_range,render_prometheus_range_query
• 注意：空格会被忽略；未知工具名称会被忽略

启用写入（X-Chrono-MCP-Enable-Writes）

默认情况下，写入工具处于隐藏状态，且无法调用。服务运维人员必须先通过 server.tools.enableWrites: true 允许写入。HTTP 和 SSE 客户端还必须将此标头设为 true；此标头无法覆盖已禁用的服务设置。其他值不会启用写入。

Stdio 没有请求标头，因此仅需服务设置即可为此传输方式启用写入。服务使用的 Chronosphere 凭据仍必须具有执行相应 API 操作的权限。

Cursor/VSCode

{
    "mcpServers": {
        "chronosphere": {
            "url": "https://<org name>.chronosphere.io/api/mcp/mcp",
            "headers": {
                "Authorization": "Bearer <chronosphere api token>",
                "X-Chrono-MCP-Disable-Tools": "<optional list of tools to disable>"
            }
        }
    }
}

此配置适用于 Cursor 和 VSCode。若要改用 OAuth 而非 Chronosphere API token，请省略 headers 部分。 移除 X-Chrono-MCP-Disable-Tools 即可显示所有工具。

VSCode 的更多详情请见此处，Cursor 的更多详情请见此处

Claude code

将 Chronosphere MCP 服务添加到 Claude code

claude mcp add -t http \
  -H "Authorization: Bearer ${CHRONOSPHERE_API_TOKEN}" \
  -H "X-Chrono-MCP-Disable-Tools: <list of tools to disable>" \
  chronosphere "https://${CHRONOSPHERE_ORG_NAME}.chronosphere.io/api/mcp/mcp"

如果你使用 OAuth，可以省略 Authorization 标头。进入 Claude 后，输入 /mcp 并选择服务以登录并触发 OAuth 流程。 移除 X-Chrono-MCP-Disable-Tools 标头即可显示所有工具。

更多详情请见此处

Codex CLI

experimental_use_rmcp_client = true
[mcp_servers.chronosphere]
url = "https://<org_name>.chronosphere.io/api/mcp/mcp"
bearer_token = "<chronosphere api token>"

若要通过 OAuth 登录，必须启用 experimental_use_rmcp_client = true，然后运行 codex mcp login chronosphere

更多详情请见此处

Gemini CLI

CHRONOSPHERE_ORG_NAME=<your org>
CHRONOSPHERE_API_TOKEN=<your api token>
gemini mcp add chronosphere "https://${CHRONOSPHERE_ORG_NAME}.chronosphere.io/api/mcp/mcp" \
  -H "Authorization: Bearer ${CHRONOSPHERE_API_TOKEN}" \
  -H "X-Chrono-MCP-Disable-Tools: <list of tools to disable>"

# Drop the -H authorization header option if you want to use OAuth.

更多信息请参阅 Gemini MCP 文档。

从源代码构建

首先构建二进制文件

make chronomcp

{
  "mcpServers": {
    "chronosphere-mcp": {
      "command": "<PATH/TO/REPO>/bin/chronomcp",
      "args": [
        "-c",
        "<PATH/TO/REPO>/config.yaml"
      ],
      "env": {
        "CHRONOSPHERE_ORG_NAME": "<your org here>",
        "CHRONOSPHERE_API_TOKEN": "<your api token here>"
      }
    }
  }
}

开发

运行服务端

Chronosphere 身份验证

此 MCP 服务使用与 chronoctl 相同的身份验证方法。默认情况下，Makefile 预期 API token 存储在 .chronosphere_api_token 中。

运行 MCP 服务端

make run-chronomcp CHRONOSPHERE_ORG_NAME=<your org here> CHRONOSPHERE_API_TOKEN=<your api token here>

API 规范

generated/ 中的 API 客户端由 Chronosphere 公共 API 规范生成：generated/configv1/spec.json、generated/datav1/spec.json 和 generated/statev1/spec.json 是 monorepo 中 src/gateway/publicapiswagger/data/ 下导出文件的副本。若要更新这些文件，请从 monorepo 检出目录同步全部三个文件，然后重新生成：

make swagger-sync MONOREPO=<path to monorepo checkout>
make all-gen

调试 MCP 工具

MCP 项目提供了一个检查器，可用于直接调用工具 API。使用方法：

1. 使用 streamable http 传输启动 MCP 服务：make run-chronomcp CONFIG_FILE=./config.http.yaml CHRONOSPHERE_ORG_NAME=<your org here>
2. 运行 npx @modelcontextprotocol/inspector node build/index.js。
3. 打开 http://localhost:6274/#resources，在 URL 中填写 http://0.0.0.0:8081/mcp，并将传输类型设为 Streamable HTTP。

可用工具

分组	工具名称	描述
configapi	get_classic_dashboard	获取 classic-dashboards 资源
configapi	get_dashboard	获取 dashboards 资源
configapi	get_drop_rule	获取 drop-rules 资源
configapi	get_mapping_rule	获取 mapping-rules 资源
configapi	get_monitor	获取 monitors 资源
configapi	get_notification_policy	获取 notification-policies 资源
configapi	get_recording_rule	获取 recording-rules 资源
configapi	get_rollup_rule	获取 rollup-rules 资源
configapi	get_slo	获取 slos 资源
configapi	list_classic_dashboards	列出 classic-dashboards 资源
configapi	list_dashboards	列出 dashboards 资源
configapi	list_drop_rules	列出 drop-rules 资源
configapi	list_mapping_rules	列出 mapping-rules 资源
configapi	list_monitors	列出 monitors 资源
configapi	list_notification_policies	列出 notification-policies 资源
configapi	list_recording_rules	列出 recording-rules 资源
configapi	list_rollup_rules	列出 rollup-rules 资源
configapi	list_slos	列出 slos 资源
configapi	update_dashboard	替换由 slug 标识的仪表板。使用 dry_run 可在不保存的情况下进行验证。
events	get_events_metadata	列出可用于查询事件的属性
events	list_events	根据给定查询列出事件
events	list_events_label_values	列出给定标签名称的值
logs	get_log	根据 ID 获取完整日志消息。ID 是日志的唯一标识符。除非设置 start 或 end，否则会搜索最近 7 天；设置它们即可查找更早的日志。
logs	get_log_histogram	根据给定查询获取日志直方图
logs	list_log_field_names	已弃用：不再支持，始终返回错误。列出日志的字段名称
logs	list_log_field_values	按出现频率从高到低列出日志字段值，并显示每个值对应的匹配日志数量。若要查看日志包含哪些字段，请将其 logID 传递给 get_log 工具。
logs	query_logs_range	执行日志范围查询。此端点以 timeSeries 或 gridData 格式返回日志。它可能返回大量数据，因此请谨慎将此操作的结果放入上下文中。U...
metric_usage	list_metric_usages_by_label_name	按标签名称分组列出指标使用情况统计信息。可用于查找可删除的未使用或高基数标签。响应字段：- label_name：标签名称 - dpps：数据点...
metric_usage	list_metric_usages_by_metric_name	按指标名称分组列出指标使用情况统计信息。可用于查找可删除以降低成本的未使用或利用率低的指标。响应字段：- metric_name：指标名称 ...
metric_usage	list_rule_evaluations	列出监控器和 recording rules 的规则评估问题。可用于识别失败或出现问题的规则。响应字段：- rule_slug：规则的唯一标识符 - rule_typ...
metrics	list_prometheus_label_names	返回与给定选择器匹配的指标上可用的标签名称（键）列表。当你需要发现特定指标或服务有哪些可用标签时，请使用此工具。示例...
metrics	list_prometheus_label_values	返回特定标签名称对应的值列表，可选按选择器筛选。当你知道标签名称并想了解它在各项指标中的取值时，请使用此工具。常...
metrics	list_prometheus_series	返回与给定选择器匹配的完整时间序列（包含所有键值对的完整标签集）。每个结果都显示一个活跃时间序列的确切标签组合。使用此工...
metrics	list_prometheus_series_metadata
metrics	query_prometheus_instant	在单个时间点计算 Prometheus 即时查询
metrics	query_prometheus_range	在指定时间范围内执行 Prometheus PromQL 查询，并以 JSON 格式返回时间序列数据点。支持标准 PromQL 语法以及 Chronosphere 自定义函数：- cardinality_estimat...
metrics	render_prometheus_range_query	在一段时间范围内计算 Prometheus 表达式查询，并将结果渲染为 PNG 图像。
monitors	list_alerts	列出 Chronosphere 中由监控器和 SLO 触发的告警，默认按时间从新到旧排列。五个搜索筛选条件（monitor_slugs、monitor_name_contains、slo_slugs、slo_name_contains 和 alert_title_contai...
monitors	list_monitor_statuses	列出 Chronosphere 中监控器的当前状态。返回所有符合筛选条件且有触发中告警的监控器。未触发告警的监控器不会出现在结果中。每个状态都带有...
traces	list_traces	根据给定查询列出追踪
注意：工具更新后若要重新生成此表，请运行：make tools-gen && go run scripts/generate-tools-table.go

发布

我们使用 goreleaser 管理发布。

你需要一个 github token，并将其放入 .github_release_token 文件中。 该令牌至少需要以下权限

• content: write
• issues: write

要创建新版本，先创建一个标签：

git tag vX.Y.Z
git push origin vX.Y.Z

然后运行以下命令，试运行发布流程：

```sh
make release-dry-run
# verify the release looks good, then run:
make release