Sentry MCP

官方

官方 Sentry MCP 伺服器，用於調查來自 AI 編碼代理的問題、錯誤報告、追蹤與效能監控資料。

你可以用 Sentry MCP 做什麼？

調查錯誤與問題 — 請您的助理提取 Sentry 錯誤詳情、堆疊追蹤和問題上下文，以進行除錯。
追蹤效能問題 — 讓您的助理分析分散式追蹤和效能資料，以 pinpoint 效能瓶頸。
使用自然語言搜尋 — 利用 AI 驅動的搜尋，以純英文描述您要找的內容，查詢錯誤、追蹤、日誌或問題。
分類與管理專案 — 請您的助理檢查專案健康狀態、檢視團隊指派，或處理專案層級的設定。
為自架 Sentry 進行設定 — 將 MCP 伺服器指向您自己的 Sentry 執行個體，並調整啟用了哪些技能（例如 inspect 或 seer）。

託管 MCP 伺服器

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

可安裝到 Claude Code、Codex、Cursor 等客戶端

文件

Sentry 工具組

此儲存庫包含 Sentry CLI、Sentry MCP 伺服器，以及共享套件。關於 CLI，請參閱 CLI 指南及發布於 https://cli.sentry.dev/ 的公開文件。文件索引涵蓋了兩個產品及共享的貢獻者指南。

Sentry MCP

Sentry 的 MCP 服務主要設計給人機協作的編碼代理（human-in-the-loop coding agents）。我們在工具選擇與優先順序上，專注於開發者工作流程與除錯使用案例，而非提供涵蓋所有 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 中建立具有必要權限範圍的使用者驗證權杖（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 不屬於自架 Sentry 的一部分，因此每當 --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 技能，因為 Seer 在自架 Sentry 上不可用。對於確實執行 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"
      }
    }
  }
}

MCP Inspector

MCP 包含一個 Inspector，方便測試服務：

pnpm inspector

輸入 MCP 伺服器 URL（http://localhost:5173）並點擊連線。這應該會觸發您的驗證流程。

注意：如果您在 127.0.0.1 存取 inspector 時遇到 OAuth 流程問題，請嘗試造訪 http://localhost:6274 改用 localhost。

本地開發

若要貢獻變更，您需要設定本地環境：

設定環境與代理技能：
```
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
```
在 Sentry 中建立 OAuth 應用程式（設定 => API => 應用程式）：
- 首頁 URL：http://localhost:5173
- 授權重新導向 URI：http://localhost:5173/oauth/callback
- 記下您的 Client ID 並產生 Client 密鑰
設定您的憑證：
- 編輯根目錄中的 .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
啟動開發伺服器：
```
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）來協助識別 pull request 中的潛在問題。這些工具提供有用的回饋與建議，但我們不建議將這些檢查設為必要條件，因為其準確性仍在演進中，可能產生誤判。

自動化審查應被視為：

✅ 有用的建議，可在程式碼審查時參考
✅ 討論與改進的起點
❌ 非合併 PR 的阻擋條件
❌ 非人工程式碼審查的替代品

在處理自動化回饋時，請專注於底層的關注點，而非嚴格遵循每一項建議。

貢獻者文件

想要貢獻嗎？請從工具組文件索引開始，取得 CLI、MCP 及共享指南。儲存庫規則請參閱 AGENTS.md，CLI 特定規則請參閱 packages/cli/AGENTS.md。