Sentry MCP

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 錯誤、問題、追蹤或效能時，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 應用程式（Settings => 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）來協助識別 Pull Request 中的潛在問題。這些工具提供有幫助的回饋與建議，但我們不建議將這些檢查設為必要條件，因為其準確性仍在演進中，且可能產生誤判。

自動化審查應被視為：

• ✅ 有用的建議，可在程式碼審查期間納入考量
• ✅ 討論與改進的起點
• ❌ 非合併 PR 的阻斷條件
• ❌ 非人工程式碼審查的替代品

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

貢獻者文件

想要貢獻或探索完整的文件地圖嗎？請參閱 CLAUDE.md（也可作為 AGENTS.md 取得）了解貢獻者工作流程與完整的文件索引。docs/ 資料夾包含各主題指南與工具整合的 .md 檔案。