Sentry MCP

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_events、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。

某些功能（如 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'

# 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-..."
      }
    }
  }
}

如果您未设置 host 变量，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
   • 记下您的客户端 ID 并生成客户端密钥

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 agent mode (use_sentry tool only)
pnpm -w run cli --agent "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 测试： 有关构建、运行和测试 stdio 实现的完整指南，请参阅 docs/testing/stdio.md（IDE、MCP Inspector）
• 远程测试： 有关测试远程服务器的完整指南，请参阅 docs/testing/remote.md（OAuth、Web UI、CLI 客户端）

开发说明

自动化代码审查

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

自动化审查应被视为：

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

在处理自动化反馈时，应关注潜在问题，而非严格遵循每条建议。

贡献者文档

想要贡献或探索完整的文档地图？请参阅 CLAUDE.md（也可通过 AGENTS.md 访问），了解贡献者工作流和完整的文档索引。docs/ 文件夹包含按主题划分的指南和工具集成的 .md 文件。