sentry-mcp

Sentry的MCP服务主要为人机协同编程代理设计。我们的工具选择和优先级聚焦于开发者工作流和调试场景，而非为所有Sentry功能提供通用型MCP服务器。

这个远程MCP服务器作为上游Sentry API的中间件，专为Cursor、Claude Code等编程助手及类似开发工具优化。其基于Cloudflare关于远程MCP的研究成果。

快速开始

访问生产环境部署的服务即可获取所需信息：

https://mcp.sentry.dev

如需贡献代码、了解工作原理或为自托管Sentry运行此服务，请继续阅读下文。

Stdio与远程模式对比

虽然本仓库主要作为MCP服务运行，但我们也支持stdio传输协议。该功能仍在完善中，但这是适配自托管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

需要连接自托管部署？运行命令时添加--host参数（仅主机名，如--host=sentry.example.com）。

注：也可使用环境变量：

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）并连接，将自动触发认证流程。

注意：若在127.0.0.1访问检查器时遇到OAuth流程问题，可尝试改用localhost访问http://localhost:6274。

本地开发

贡献代码需配置本地环境：

1. 设置环境文件：

   make setup-env  # 从示例文件创建.env配置
   

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

   • 主页URL: http://localhost:5173
   • 授权回调URI: http://localhost:5173/oauth/callback
   • 记录Client ID并生成Client secret

3. 配置凭证：

   • 编辑根目录.env添加OPENAI_API_KEY
   • 编辑packages/mcp-cloudflare/.env添加：
     • SENTRY_CLIENT_ID=你的开发客户端ID
     • SENTRY_CLIENT_SECRET=你的开发客户端密钥
     • COOKIE_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?"

# 测试代理模式(仅use_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实现的完整指南（含IDE和MCP检查器）
• 远程测试： 参见docs/testing-remote.md获取测试远程服务器的完整指南（含OAuth、网页界面和CLI客户端）

开发说明

自动化代码审查

本仓库使用自动化代码审查工具（如Cursor BugBot）辅助识别PR中的潜在问题。这些工具提供建设性反馈，但不建议设为强制检查项，因其准确性仍在演进且可能产生误报。

自动化审查应视为：

• ✅ 代码审查时的参考建议
• ✅ 讨论和改进的起点
• ❌ 非合并PR的硬性要求
• ❌ 不可替代人工代码审查

处理自动化反馈时，应关注问题本质而非机械遵循每条建议。

贡献者文档

贡献代码或查阅完整文档？请参阅CLAUDE.md（同见于AGENTS.md）了解贡献者工作流和完整文档索引。docs/目录包含各主题指南和工具集成的.mdc文件。