Sentry MCP

官方

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

GitHub
849
试用此 MCP赞助

你可以用 Sentry MCP 做什么？

  • 调查错误和问题 — 让您的助手在编码会话期间调取 Sentry 错误详情、堆栈跟踪和问题上下文以进行调试。
  • 追踪性能问题 — 让您的助手分析分布式追踪和性能数据，以定位慢事务或瓶颈。
  • 用自然语言搜索事件 — 使用 search_events 让您的助手将纯英文查询转换为 Sentry 的搜索语法，以查找相关事件。
  • 分类和管理问题 — 指示您的助手直接从编码工作流中审查、分配或更新问题状态。
  • 查询项目和团队信息 — 检索 Sentry 组织、项目和团队元数据，以在调试时了解所有权和范围。

托管 MCP 服务器

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

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

文档

sentry-mcp

Sentry 的 MCP 服务主要面向人机协作（human-in-the-loop）的编码代理设计。我们的工具选择和优先级聚焦于开发者工作流和调试场景，而不是为所有 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 错误、问题（issue）、跟踪（trace）或性能的问题时，Claude 会自动委派给它。

如需前瞻性的工具变体和功能：

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

Stdio 与远程模式对比

虽然本仓库专注于作为 MCP 服务运行，我们也支持 stdio 传输方式。这仍处于开发中，但这是针对自托管 Sentry 实例运行 MCP 的最简单方式。

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

要使用 stdio 传输方式，你需要在 Sentry 中创建一个具有所需权限范围的用户认证令牌（User Auth Token）。截至撰写本文时，所需权限为：

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。

某些功能（如 Seer）在自托管实例上可能不可用。你可以禁用特定技能，以防止暴露不受支持的工具：

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

对于没有 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
MCP_DISABLE_SKILLS=          # Disable specific skills (comma-separated, e.g. 'seer')

重要提示： 始终设置 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 时才需要设置该覆盖值。

对于不支持 Seer 的自托管实例：

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

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 应用（设置 => 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 并点击连接。按照提示操作后，你将能够"列出工具"（List Tools）。

测试

包含三个测试套件：单元测试、评估测试和手动测试。

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

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 的非阻塞要求
  • ❌ 人工代码审查的替代品

在回应自动化反馈时，应关注底层问题，而不是严格遵循每一条建议。

贡献者文档

想要参与贡献或浏览完整的文档地图？参见 CLAUDE.md（也可作为 AGENTS.md 使用）了解贡献者工作流和完整的文档索引。docs/ 文件夹包含按主题划分的指南和工具集成的 .md 文件。