Sentry MCP

官方

用于调查来自AI编码代理的问题、错误报告、追踪和性能监控数据的官方Sentry MCP服务器。

GitHub
952

你可以用 Sentry MCP 做什么？

  • 搜索错误和追踪 — 使用自然语言查询，让你的助手搜索 Sentry 错误和追踪。
  • 搜索问题和日志 — 以对话方式查询 Sentry 问题和日志，由 AI 将请求转换为 Sentry 查询语法。
  • 使用编程代理调试 — 使用 Claude Code 插件，让 Claude 将有关 Sentry 错误、问题、追踪和性能的问题委派给 sentry-mcp 子代理。
  • 连接自托管的 Sentry — 使用 --host 通过 stdio 传输连接到自托管实例；对于纯 HTTP 部署，还需使用 --insecure-http。
  • 控制公开的技能 — 在远程连接中使用 ?skills= 或 ?disable-skills= 缩小可用工具范围；在本地使用 MCP_SKILLS/MCP_DISABLE_SKILLS。

托管 MCP 服务器

npx add-mcp 'https://mcp.sentry.dev/mcp'

可安装到 Claude Code、Codex、Cursor 等客户端

文档

Sentry Toolkit

此仓库包含 Sentry CLI、Sentry MCP 服务器和共享软件包。有关 CLI，请参阅 CLI 指南 和已发布的文档 https://cli.sentry.dev/。文档索引 涵盖这两款产品以及共享的贡献者指南。

独立的 Docs MCP Worker 提供文档搜索和由 docs.sentry.io 支持的 AI 生成答案。

Sentry MCP

Sentry 的 MCP 服务主要面向有人参与的编码代理。我们的工具选择和优先级侧重于开发者工作流和调试场景，而非提供涵盖 Sentry 所有功能的通用 MCP 服务器。

此远程 MCP 服务器充当上游 Sentry API 的中间件，并针对 Cursor、Claude Code 等编码助手和类似开发工具进行了优化。它基于 Cloudflare 在远程 MCP 方面的工作。

入门

访问已部署的生产服务，即可了解所需的一切：

https://mcp.sentry.dev

如果你想贡献代码、了解其工作原理，或在自托管的 Sentry 上运行此服务，请继续阅读下文。

Claude Code 插件

安装为 Claude Code 插件，以自动委派给子代理：

claude plugin marketplace add getsentry/sentry-mcp
claude plugin install sentry-mcp@sentry-mcp

这会提供一个 sentry-mcp 子代理；当你询问 Sentry 错误、问题、追踪或性能相关内容时，Claude 会自动将任务委派给它。

有关面向未来的工具变体和功能：

claude plugin install sentry-mcp@sentry-mcp-experimental

Stdio 与远程模式

虽然此仓库专注于作为 MCP 服务运行，但也支持 stdio 传输方式。此功能仍在开发中，但这是在自托管的 Sentry 安装上运行 MCP 的最简单方式。

注意： AI 驱动的搜索工具（search_errors、search_traces、search_logs、search_issues 等）需要 LLM 提供商（OpenAI、Azure OpenAI、Anthropic 或 OpenRouter）。这些工具使用自然语言处理将查询转换为 Sentry 的查询语法。未配置提供商时，这些特定工具将不可用，但其他所有工具仍可正常运行。

要使用 stdio 传输方式，你需要在 Sentry 中创建具有必要权限范围的用户身份验证令牌。截至本文撰写时，所需权限如下：

org:read
project:read
project:write
team:read
team:write
event:write

启动传输：

npx @sentry/mcp-server@latest --access-token=sentry-user-token

需要连接到自托管部署？运行命令时添加 --host（仅主机名，例如 --host=sentry.example.com）。 对于仅提供普通 HTTP 的隔离内部部署，还需添加 --insecure-http。

自托管的 Sentry 不包含 Seer，因此当 --host 指向非 sentry.io 主机时，默认技能集会排除 seer 技能。如果你的自托管部署确实运行 Seer，可以显式启用该技能：

npx @sentry/mcp-server@latest --access-token=TOKEN --host=sentry.example.com --skills=inspect,seer

你也可以禁用其他技能，以避免暴露不受支持的工具：

npx @sentry/mcp-server@latest --access-token=TOKEN --host=sentry.example.com --disable-skills=project-management

对于未启用 TLS 的自托管实例：

npx @sentry/mcp-server@latest --access-token=TOKEN --host=sentry.internal:9000 --insecure-http

使用显式 Sentry 令牌进行远程连接

支持自定义 HTTP 标头的远程客户端可以直接将上游 Sentry API 令牌传递给 Cloudflare 传输：

{
  "mcpServers": {
    "sentry": {
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Sentry-Bearer ${SENTRY_ACCESS_TOKEN}"
      }
    }
  }
}

Sentry-Bearer 与 Bearer 有意区分：Bearer 专用于 MCP OAuth 访问令牌。使用 Sentry-Bearer 时，worker 不会存储、验证、交换或刷新上游令牌。它会通过 OAuth 会话使用的相同 Sentry API 调用转发令牌，而令牌的有效期和刷新仍由客户端或上游提供商负责。

直接远程身份验证默认启用所有活动的 MCP 技能。你可以使用 ?skills=inspect,triage 或 ?disable-skills=seer 缩小所暴露工具的范围。

环境变量

SENTRY_ACCESS_TOKEN=         # Required: Your Sentry auth token

# LLM Provider Configuration (required for AI-powered search tools)
EMBEDDED_AGENT_PROVIDER=     # Required when multiple provider keys are set: 'openai', 'azure-openai', 'anthropic', or 'openrouter'
OPENAI_API_KEY=              # Required if using OpenAI
ANTHROPIC_API_KEY=           # Required if using Anthropic
OPENROUTER_API_KEY=          # Required if using OpenRouter
OPENROUTER_MODEL=            # Optional OpenRouter model, defaults to 'openai/gpt-5.6-luna'
OPENROUTER_REASONING_EFFORT= # Optional OpenRouter reasoning effort, defaults to 'high'

# Optional overrides
SENTRY_HOST=                 # For self-hosted deployments (drops 'seer' from the default skills)
MCP_SKILLS=                  # Grant specific skills (comma-separated, e.g. 'inspect,seer')
MCP_DISABLE_SKILLS=          # Disable specific skills (comma-separated, e.g. 'project-management')

重要： 始终设置 EMBEDDED_AGENT_PROVIDER，以明确指定 LLM 提供商。仅根据 API 密钥自动检测提供商的方式已弃用，并将在未来版本中移除。有关详细配置选项，请参阅 docs/operations/embedded-agents.md。

MCP 配置示例

{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["@sentry/mcp-server"],
      "env": {
        "SENTRY_ACCESS_TOKEN": "your-token",
        "EMBEDDED_AGENT_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

如果未设置主机变量，CLI 会自动连接到 Sentry SaaS 服务。仅在使用自托管 Sentry 时设置此覆盖项。

将 SENTRY_HOST 设置为自托管主机时，默认集合也会移除 seer 技能，因为自托管的 Sentry 不提供 Seer。对于确实运行 Seer 的自托管部署，可使用 MCP_SKILLS 启用该技能：

{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["@sentry/mcp-server"],
      "env": {
        "SENTRY_ACCESS_TOKEN": "your-token",
        "SENTRY_HOST": "sentry.example.com",
        "MCP_SKILLS": "inspect,seer"
      }
    }
  }
}

速率限制

工具调用受 Sentry API 速率限制约束。对于触发速率限制的请求，以及读取请求中 Sentry 服务器的暂时性错误，MCP 服务器会在短暂等待后重试。如果限制持续时间较长，工具会返回一条 Rate Limited 消息，告知何时可以重试。代理最常因并行运行大量 Sentry 工具调用而触及每秒限制，因此如果看到此消息，请逐个运行这些调用。

MCP Inspector

MCP 提供了一个 Inspector，方便你测试服务：

pnpm inspector

输入 MCP 服务器 URL（http://localhost:5173），然后点击连接。这应该会为你启动身份验证流程。

注意：如果在 127.0.0.1 上访问 Inspector 时 OAuth 流程遇到问题，请访问 http://localhost:6274，改用 localhost。

本地开发

要贡献更改，你需要设置本地环境：

  1. 设置环境和代理技能：

    make setup-env  # Creates .env files and installs shared agent skills

    此操作还会运行 npx @sentry/dotagents install，将 getsentry/skills 中的共享技能安装到 .agents/skills/（并通过符号链接关联到 .claude/skills 和 .cursor/skills）。之后如需更新技能，可直接运行：

    npx @sentry/dotagents install

  2. 在 Sentry 中创建 OAuth 应用（Settings => API => Applications）：

    • 主页 URL：http://localhost:5173
    • 授权重定向 URI：http://localhost:5173/oauth/callback
    • 记下 Client ID 并生成 Client secret

  3. 配置凭据：

    • 编辑根目录中的 .env，并添加 OPENAI_API_KEY 或 OPENROUTER_API_KEY
    • 编辑 packages/mcp-cloudflare/.env 并添加：
      • SENTRY_CLIENT_ID=your_development_sentry_client_id
      • SENTRY_CLIENT_SECRET=your_development_sentry_client_secret
      • COOKIE_SECRET=my-super-secret-cookie

  4. 启动开发服务器：

    pnpm dev

验证

在本地运行服务器，使其可通过 http://localhost:5173 访问

pnpm dev

要测试本地服务器，请在 Inspector 中输入 http://localhost:5173/mcp 并点击连接。按照提示操作后，即可“列出工具”。

测试

此项目包含三套测试：单元测试、评估和手动测试。

单元测试可通过以下命令运行：

pnpm test

评估需要在项目根目录中创建一个 .env 文件，并添加一些配置：

# .env (in project root)
OPENAI_API_KEY=      # Use OpenAI-backed AI-powered tools
OPENROUTER_API_KEY=  # Or use OpenRouter-backed AI-powered tools

注意：根目录中的 .env 文件为所有软件包提供默认值。各个软件包可以有自己的 .env 文件，以便在开发期间覆盖这些默认值。

完成后，可通过以下命令运行评估：

pnpm eval

手动测试（推荐用于测试 MCP 更改）：

# Test with local dev server (default: http://localhost:5173)
pnpm -w run cli "who am I?"

# Test against production
pnpm -w run cli --mcp-host=https://mcp.sentry.dev "query"

# Test with local stdio mode (requires SENTRY_ACCESS_TOKEN)
pnpm -w run cli --access-token=TOKEN "query"

注意：CLI 默认使用 http://localhost:5173。使用 --mcp-host 覆盖，或设置 MCP_URL 环境变量。

全面测试指南：

  • Stdio 测试： 请参阅 docs/testing/stdio.md，了解构建、运行和测试 stdio 实现（IDE、MCP Inspector）的完整指南
  • 远程测试： 请参阅 docs/testing/remote.md，了解测试远程服务器（OAuth、Web UI、CLI 客户端）的完整指南

开发说明

自动化代码审查

此仓库使用自动化代码审查工具（如 Cursor BugBot）帮助识别拉取请求中的潜在问题。这些工具会提供有用的反馈和建议，但我们不建议将这些检查设为必需项，因为其准确性仍在不断改进，也可能产生误报。

自动化审查应视为：

  • ✅ 有帮助的建议，可在代码审查期间参考
  • ✅ 讨论和改进的起点
  • ❌ 不是合并 PR 的阻塞性要求
  • ❌ 不能替代人工代码审查

处理自动化反馈时，应关注其背后的问题，而不是严格照搬每一条建议。

贡献者文档

想要贡献代码？请从 Toolkit 文档索引 开始，查阅 CLI、MCP 和通用指南。仓库规则请参阅 AGENTS.md，CLI 专属规则请参阅 packages/cli/AGENTS.md。