Scout Monitoring MCP

Scout Monitoring MCP

本仓库包含用于在本地运行 MCP 服务器的代码，该服务器可通过 Scout 的 API 访问 https://www.scoutapm.com 数据。我们提供了一个 Docker 镜像，你的 AI 助手可以拉取并运行它，以访问 Scout Monitoring 数据。

这使 Scout Monitoring 的性能和错误数据直接掌握在你的 AI 助手手中。适用于 Rails、Django、FastAPI、Laravel 等。使用它来获取带有代码行信息的追踪和错误，AI 可以利用这些信息在你的编辑器和代码库中直接定位修复。N+1 查询、慢端点、慢查询、内存膨胀、吞吐量问题——所有你熟悉的性能问题都会在你工作的地方被呈现和解释。

如果这让你的生活好了一点点，为什么不给它点个 :star: 呢？！

设置向导

配置并开始使用 Scout MCP 的最简单方式是使用我们的交互式设置向导。它会为你处理所有前置条件和安装步骤。

通过 npx 运行：

npx @scout_apm/wizard

从源码构建并运行：

cd ./wizard
npm install
npm run build
node dist/wizard.js

向导将引导你完成：

• 选择你的 AI 编码平台（Cursor、Claude Code、Claude Desktop）
• 输入你的 Scout API 密钥
• 自动配置 MCP 服务器设置

支持的平台

向导目前支持以下平台的设置：

• Cursor - 自动配置 MCP 设置
• Claude Code (CLI) - 提供正确的运行命令
• Claude Desktop - 更新 Windows/Mac 的配置文件

对于其他所有平台，它会输出 JSON，你可以复制/粘贴到你的 AI 助手的 MCP 配置中。

前置条件

向导是入门的好方法，但你也可以手动进行设置。你需要拥有或创建一个 Scout Monitoring 账户并获取 API 密钥。

1. https://scoutapm.com/users/sign_up?utm_source=github&utm_medium=github&utm_campaign=scout-mcp-local
2. 在你的应用中安装 Scout Agent 并发送 Scout 数据！
   • Ruby
   • Python
   • PHP
   • 如果你在本地试用，请确保在配置中设置了 monitor: true、errors_enabled: true 以获得最佳体验
3. 访问设置以获取或创建 API 密钥
   • 这_不是_你的“Agent Key”；而是在设置页面上可以创建的“API Key”
   • 这是一个只读密钥，只能访问你账户中的数据
4. 安装 Docker。以下说明假设你可以启动 Docker 容器

目前，如果未在环境变量中或通过启动时的命令行参数设置 API 密钥，MCP 服务器将无法启动。

安装

我们建议使用提供的 Docker 镜像来运行 MCP 服务器。它旨在由你的 AI 助手启动，并配置你的 Scout API 密钥。许多本地客户端允许在某个位置指定运行 MCP 服务器的命令。下面提供了几个示例。

Docker 镜像可在 Docker Hub 上获取。

当然，你始终可以克隆此仓库并直接运行 MCP 服务器；建议使用 uv 或其他环境管理工具。

配置本地客户端（例如 Claude/Cursor/VS Code Copilot）

如果你想手动配置 MCP，这通常只需在你的 AI 助手配置中提供一个命令，在环境中带上你的 API 密钥来运行 MCP 服务器。以下是 JSON 的结构（顶层键各不相同）：

{
  "mcpServers": {
    "scout-apm": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env", "SCOUT_API_KEY", "scoutapp/scout-mcp-local"],
      "env": { "SCOUT_API_KEY": "your_scout_api_key_here"}
    }
  }
}

claude mcp add scoutmcp -e SCOUT_API_KEY=your_scout_api_key_here -- docker run --rm -i -e SCOUT_API_KEY scoutapp/scout-mcp-local

{
  "mcpServers": {
    "scout-apm": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env", "SCOUT_API_KEY", "scoutapp/scout-mcp-local"],
      "env": { "SCOUT_API_KEY": "your_scout_api_key_here"}
    }
  }
}

使用 Scout Monitoring MCP

Scout 的 MCP 旨在将错误和性能数据直接放到你的 AI 助手的……手中？使用它来获取带有代码行信息的追踪和错误，AI 可以利用这些信息在你的编辑器中直接定位修复。

大多数助手会同时显示原始工具调用并进行分析。桌面助手可以轻松创建自定义 JS 应用程序来探索你想要的任何数据。集成到代码编辑器中的助手可以使用追踪数据和错误回溯信息在你的代码库中直接进行修复。

将 Scout 的 MCP 与你的 AI 助手的其他工具结合使用，可以：

• 基于错误和性能数据创建丰富的 GitHub/GitLab issue
• 让 JIRA 变得有趣——让你的 AI 助手创建包含所有细节的工单
• 生成修复特定错误和性能问题的 PR

工具

Scout MCP 提供以下工具来访问 Scout APM 数据：

• list_apps - 列出可用的 Scout APM 应用，可选按最后活跃日期过滤
• get_app_metrics - 获取特定应用的单项指标数据（response_time、throughput 等）
• get_app_endpoints - 获取应用的所有端点及其聚合性能指标
• get_endpoint_metrics - 获取应用中特定端点的时间序列指标
• get_app_endpoint_traces - 获取应用过滤到特定端点的最近追踪
• get_app_trace - 获取包含所有 span 和详细执行信息的单条追踪
• get_app_error_groups - 获取应用的最近错误组，可选按端点过滤
• get_app_insights - 获取性能洞察，包括 N+1 查询、内存膨胀和慢查询

资源

Scout MCP 以资源形式提供配置模板，你的 AI 助手可以读取并应用：

• scoutapm://config-resources/{framework} - 受支持框架或库（rails、django、flask、fastapi）的设置说明
• scoutapm://config-resources/list - 列出所有可用的配置模板
• scoutapm://metrics - 列出 Scout APM 所有可用的指标

实用提示词

设置与配置

• “帮我为我的 Rails 应用设置 Scout 监控”
• “为我的 Django 项目创建 Scout APM 配置文件，密钥为 ABC123”

性能与监控

• “总结 Scout Monitoring MCP 中可用的工具。”
• “查找应用 my-app-name 在过去 7 天内最慢的端点。生成一个包含平均响应时间、吞吐量和 P95 响应时间的结果表格。”
• “显示应用 Foo 在过去 24 小时内出现频率最高的错误。获取最新的错误详情，检查回溯信息并建议修复方案。”
• “获取应用 Bar 最近的任何 n+1 洞察。按 id 拉取具体的追踪，并根据回溯数据帮我优化它。”

Token 用量

我们目前更感兴趣的是扩展可用信息，而不是严格控制 MCP 工具的响应大小。如果你的 AI 助手有可配置的 token 限制（例如 Claude Code export MAX_MCP_OUTPUT_TOKENS=50000），我们建议将其设置得足够高，例如 50,000 个 token。

本地开发

我们使用 uv 和 taskipy 来管理环境并运行此项目的任务。

使用 Inspector 运行

uv run task dev

在 inspector 中连接以添加 API 密钥，设置为 STDIO 传输

构建 Docker 镜像

docker build -t scout-mcp-local .

发布

1. 创建分支并使用 uv run python bump_versions.py 提升版本号
2. 将其合并
3. 使用新版本创建 GitHub release（gh release create v2025.11.3 --generate-notes --draft）

发布 release 会推送 v* 标签，CI 会发布 Docker 镜像、PyPI 包，然后发布 MCP Registry 条目：

• server.json → com.scoutapm/scout-mcp-local（此服务器；其版本由 bump_versions.py 提升）
• server.remote.json → com.scoutapm/scout-monitoring（托管在 https://scoutapm.com/mcp 的服务器）。当你更改其元数据时，请手动提升其 version；未更改的版本会被跳过。

MCP Registry 密钥

注册表通过在 scoutapm.com 顶点持有 Ed25519 公钥的 DNS TXT 记录来验证我们拥有 com.scoutapm/* 命名空间。CI 使用来自 MCP_REGISTRY_PRIVATE_KEY 仓库密钥的匹配私钥登录。要轮换它：

openssl genpkey -algorithm Ed25519 -out key.pem
# Public key for the TXT record: replace the existing v=MCPv1 record, don't add a second one
echo "v=MCPv1; k=ed25519; p=$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)"
# Private key (hex) for the MCP_REGISTRY_PRIVATE_KEY secret
openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n'

供机器人使用：

mcp-name: com.scoutapm/scout-mcp-local