sentry-mcp

Sentry 的 MCP 服务主要设计用于人机协作编码代理。我们的工具选择和优先级集中在开发者工作流程和调试用例上，而不是提供一个适用于所有 Sentry 功能的通用 MCP 服务器。

此远程 MCP 服务器作为上游 Sentry API 的中间件，优化了针对像 Cursor、Claude Code 和类似开发工具的编码助手。它是基于 Cloudflare 对远程 MCP 的研究。

开始使用

您可以在生产部署的服务中找到所需的所有信息：

https://mcp.sentry.dev

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

Stdio 与远程

虽然本仓库专注于充当 MCP 服务，我们也支持 stdio 传输方式。这仍然是一个正在进行中的项目，但这是将 MCP 适应自托管 Sentry 安装的最简单方法。

注意： 基于 AI 的搜索工具（如 search_events 和 search_issues）需要 OpenAI API 密钥。这些工具使用自然语言处理将查询转换为 Sentry 的查询语法。如果没有 API 密钥，这些特定工具将不可用，但其他所有工具将正常工作。

要利用 stdio 传输，您需要在 Sentry 中创建一个具有必要范围的用户认证令牌。目前需要的范围是：

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

启动传输：

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

需要连接到自托管部署吗？在运行命令时添加 <code>--host</code>（仅主机名，例如 <code>--host=sentry.example.com</code>）。

注意：您也可以使用环境变量：

SENTRY_ACCESS_TOKEN=
# 自托管部署的可选覆盖
SENTRY_HOST=
OPENAI_API_KEY=  # 需要用于基于 AI 的搜索工具（search_events, search_issues）

如果未设置主机变量，CLI 将自动指向 Sentry SaaS 服务。只有在操作自托管的 Sentry 时才设置覆盖。

MCP 检查器

MCP 包含一个 检查器，以轻松测试服务：

pnpm inspector

输入 MCP 服务器 URL（http://localhost:5173），然后点击连接。这应该触发您的身份验证流程。

注意：如果您在访问检查器时遇到 OAuth 流程问题（例如在 127.0.0.1 上），尝试使用 localhost 访问 http://localhost:6274。

本地开发

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

1. 设置环境文件：

   make setup-env  # 从示例创建两个 .env 文件
   

2. 在 Sentry 中创建一个 OAuth 应用（设置 => API => 应用）：

   • 主页 URL：http://localhost:5173
   • 授权重定向 URI：http://localhost:5173/oauth/callback
   • 注意您的客户端 ID 并生成客户端密钥

3. 配置您的凭据：

   • 编辑根目录下的 .env 文件并添加您的 OPENAI_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

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

测试

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

单元测试可以使用以下命令运行：

pnpm test

评估需要在项目根目录下有一个 .env 文件，其中包含一些配置：

# .env（在项目根目录下）
OPENAI_API_KEY=  # 生产环境中基于 AI 的搜索工具也需要此密钥

注意：根目录下的 .env 文件为所有包提供了默认值。各包可以在开发期间拥有自己的 .env 文件来覆盖这些默认值。

完成上述步骤后，您可以使用以下命令运行它们：

pnpm eval

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

# 使用本地开发服务器测试（默认：http://localhost:5173）
pnpm -w run cli "who am I?"

# 测试代理模式（仅使用_sentry 工具）
pnpm -w run cli --agent "who am I?"

# 对生产进行测试
pnpm -w run cli --mcp-host=https://mcp.sentry.dev "query"

# 使用本地 stdio 模式测试（需要 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 实现（IDEs、MCP 检查器）的完整指南。
• 远程测试： 查看 docs/testing--remote.md 以获取关于测试远程服务器（OAuth、Web UI、CLI 客户端）的完整指南。

开发说明

自动化代码审查

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

自动化审查应被视为：

• ✅ 有用的建议 在代码审查过程中考虑
• ✅ 讨论和改进的起点
• ❌ 合并 PR 的阻塞要求
• ❌ 替代人工代码审查

在处理自动化反馈时，重点在于解决潜在问题，而不仅仅是严格遵循每条建议。

贡献者文档

想要贡献或探索完整的文档地图？查看 CLAUDE.md（也可作为 AGENTS.md 获取）以了解贡献者的工作流程和完整的文档索引。docs/ 文件夹包含按主题的指南和集成工具的 .mdc 文件。