Glowroot MCP Server

一个基于 FastMCP 框架实现的 MCP（Model Context Protocol）服务器， 让 AI 助手能够分析由 Glowroot（开源 APM 工具）捕获的 Java 应用程序 Trace。

特性

• list_recent_errors — 列出指定时间窗口内的最近错误
• analyze_trace — 深入分析指定 Trace，展示执行树和 stack trace
• find_timeout_errors — 查找超时类错误（SocketTimeoutException 等）
• analyze_error_patterns — 按事务分组分析错误模式，识别受影响最严重的事务
• get_error_by_message — 按错误消息内容搜索错误（例如 "NullPointerException"）
• 每个工具均支持 glowroot_agent_id 参数，可在调用时动态指定 Agent ID，不再依赖环境变量

配置

通过环境变量或 .env 文件配置默认值：

GLOWROOT_URL=http://localhost:4000
GLOWROOT_AGENT_ID=

变量	说明	默认值
GLOWROOT_URL	Glowroot 实例的基础 URL	http://localhost:4000
GLOWROOT_AGENT_ID	默认的 Glowroot Agent ID（多 Agent 部署时使用）	空（单 Agent）

提示：GLOWROOT_AGENT_ID 仅作为默认值。每个工具均支持可选的 glowroot_agent_id 参数， 调用时传入会覆盖默认值，便于在同一个 MCP 服务器中查询多个 Agent 的数据。

Agent ID 优先级

1. 工具调用的 glowroot_agent_id 参数（最高）
2. 环境变量 GLOWROOT_AGENT_ID
3. 空字符串（单 Agent 部署）

传输模式

MCP 支持三种传输模式，通过环境变量 MCP_TRANSPORT 配置：

模式	值	适用场景	说明
stdio	stdio（默认）	本地部署	客户端启动子进程，通过 stdin/stdout 通信
Streamable HTTP	streamable-http	远程部署（推荐）	HTTP 单端点，MCP 新规范
SSE	sse	远程部署	HTTP + Server-Sent Events，旧规范

远程模式相关的环境变量：

变量	说明	默认值
MCP_HOST	监听地址	0.0.0.0
MCP_PORT	监听端口	8000
MCP_PATH	URL 路径	/mcp（streamable-http）或 /sse（sse）

使用

本地部署（stdio 模式）

stdio 是默认传输模式，由 MCP 客户端（Claude Desktop / Kiro 等）以子进程方式拉起， 通过 stdin/stdout 通信。不要在终端里直接运行 glowroot-mcp——它只会阻塞等待 stdin 上的 MCP 协议输入，不会交互式输出任何内容。

本地使用请直接配置客户端，见下方「MCP 配置 — 本地 stdio」。

若需在命令行手动验证服务器是否可启动，可加 --help 或指定远程传输模式（见下节）， 例如 MCP_TRANSPORT=streamable-http glowroot-mcp。

远程部署（Streamable HTTP 模式）

在服务器上启动：

MCP_TRANSPORT=streamable-http MCP_PORT=8000 glowroot-mcp

服务器将在 http://0.0.0.0:8000/mcp 监听 MCP 请求。

MCP 配置 — 本地 stdio（Claude Desktop / Kiro 等）

将以下配置加入 MCP 配置文件（mcp.json）：

{
  "mcpServers": {
    "glowroot": {
      "command": "/home/YOUR_USER/.local/bin/glowroot-mcp",
      "env": {
        "GLOWROOT_URL": "http://localhost:4000",
        "GLOWROOT_AGENT_ID": ""
      }
    }
  }
}

将 /home/YOUR_USER/.local/bin/glowroot-mcp 替换为 which glowroot-mcp 的实际输出。 若 glowroot-mcp 已在 PATH 中，可直接使用 "command": "glowroot-mcp"。

MCP 配置 — 远程 Streamable HTTP（Claude Desktop / Kiro 等）

{
  "mcpServers": {
    "glowroot": {
      "url": "http://120.48.62.26:8000/mcp"
    }
  }
}

客户端通过网络访问远程 MCP 服务器，无需在本地安装 Python 或可执行文件。

MCP 配置 — 远程 SSE

{
  "mcpServers": {
    "glowroot": {
      "url": "http://120.48.62.26:8000/sse"
    }
  }
}

在工具调用中动态指定 Agent ID

所有工具都接受可选的 glowroot_agent_id 参数。例如：

list_recent_errors(hours_ago=1, glowroot_agent_id="agent-42")
analyze_trace(trace_id="abc-123", glowroot_agent_id="agent-42")

若不传入该参数，则使用环境变量 GLOWROOT_AGENT_ID 的值。

架构

本项目基于 FastMCP 框架开发：

• glowroot_mcp/server.py — 使用 FastMCP 声明工具，通过 @mcp.tool 装饰器自动生成 schema
• glowroot_mcp/glowroot.py — Glowroot HTTP API 客户端
• tests/ — 单元测试（pytest + pytest-asyncio）

FastMCP 会根据函数签名和类型注解自动生成 JSON Schema，无需手写 tools.py。

开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

依赖

• Python 3.10+
• FastMCP >= 2.0.0
• httpx >= 0.25.0
• python-dotenv >= 1.0.0
• 一个运行中的 Glowroot 实例，用于监控 Java 应用

License

MIT