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

如果你將主機變數留空，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 => 應用程式）：

   • 首頁 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 測試： 請參閱 docs/testing/stdio.md，取得建構、執行與測試 stdio 實作的完整指南（IDE、MCP Inspector）
• 遠端測試： 請參閱 docs/testing/remote.md，取得測試遠端伺服器的完整指南（OAuth、網頁 UI、CLI 用戶端）

開發注意事項

自動化程式碼審查

此儲存庫使用自動化程式碼審查工具（如 Cursor BugBot）來協助識別拉取請求中的潛在問題。這些工具提供有幫助的回饋與建議，但我們不建議將這些檢查設為必要，因為其準確性仍在演進，且可能產生誤報。

自動化審查應被視為：

• ✅ 在程式碼審查期間可考慮的實用建議
• ✅ 討論與改進的起點
• ❌ 合併 PR 的非阻擋性要求
• ❌ 人工程式碼審查的替代品

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

貢獻者文件

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