{"_id":"selfhosted-sentry-mcp","_rev":"6-7ec0958717582d2ad0fc067c81f83d68","name":"selfhosted-sentry-mcp","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.0":{"name":"selfhosted-sentry-mcp","version":"1.0.0","keywords":["mcp","modelcontextprotocol","sentry","self-hosted","debugging"],"author":{"name":"hieuda"},"license":"MIT","_id":"selfhosted-sentry-mcp@1.0.0","maintainers":[{"name":"hieuda","email":"anhhieudoan.work@gmail.com"}],"homepage":"https://github.com/HieuAnh87/sentry-selfhosted-mcp","bugs":{"url":"https://github.com/HieuAnh87/sentry-selfhosted-mcp/issues"},"bin":{"selfhosted-sentry-mcp":"build/index.js"},"dist":{"shasum":"4f870d513b102a1d10df4cf6e084a651cdbc75ed","tarball":"https://registry.npmjs.org/selfhosted-sentry-mcp/-/selfhosted-sentry-mcp-1.0.0.tgz","fileCount":4,"integrity":"sha512-0S/H6Z3eGv3PQFinyJybJ3jf4nvlJxywE6rUF0lWAPz97q8RE0+RVI2tz/2qhAmaQxhk0A2aJDyVpsvqvonbUg==","signatures":[{"sig":"MEYCIQC7QQsSno9sOtO6aDanCzBA5kDBMY1bZoEdCTMu6zISJQIhAI8quR54zSM+LKdB5e7FFD9yYumc4lyZPG4mxNnrhwIR","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":72997},"type":"module","gitHead":"f8bb458411eb0c6d1441211e65239bae7b215884","scripts":{"test":"node --test test/**/*.test.js","build":"tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"","watch":"tsc --watch","prepare":"npm run build","inspector":"npx @modelcontextprotocol/inspector build/index.js","test:smoke":"node test/smoke.test.js"},"_npmUser":{"name":"hieuda","email":"anhhieudoan.work@gmail.com"},"repository":{"url":"git+https://github.com/HieuAnh87/sentry-selfhosted-mcp.git","type":"git"},"_npmVersion":"11.6.2","description":"Model context protocol server for self-hosted Sentry instances with debugging tools.","directories":{},"_nodeVersion":"25.2.1","dependencies":{"axios":"^1.8.4","@modelcontextprotocol/sdk":"0.6.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.3","@types/node":"^20.11.24"},"_npmOperationalInternal":{"tmp":"tmp/selfhosted-sentry-mcp_1.0.0_1767671301612_0.8711319712537462","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Security: raw_sentry_api can send your Sentry auth token to arbitrary hosts. Upgrade to >=1.2.0 and rotate the token."},"1.1.0":{"name":"selfhosted-sentry-mcp","version":"1.1.0","keywords":["mcp","modelcontextprotocol","sentry","self-hosted","debugging"],"author":{"name":"hieuda"},"license":"MIT","_id":"selfhosted-sentry-mcp@1.1.0","maintainers":[{"name":"hieuda","email":"anhhieudoan.work@gmail.com"}],"homepage":"https://github.com/HieuAnh87/sentry-selfhosted-mcp","bugs":{"url":"https://github.com/HieuAnh87/sentry-selfhosted-mcp/issues"},"bin":{"selfhosted-sentry-mcp":"build/index.js"},"dist":{"shasum":"d1e212155a420e4c427a2213336bedc993e1f35e","tarball":"https://registry.npmjs.org/selfhosted-sentry-mcp/-/selfhosted-sentry-mcp-1.1.0.tgz","fileCount":4,"integrity":"sha512-VkFfmbHd7olaCGwc/Z624ittfKjLDof9SBqluvaoZdEfpHDfMasQ8VXsLq1wq2+Rb58T0YdXMIHecY+ETMReIA==","signatures":[{"sig":"MEQCIGwYE1Ytn07wlMR+4KEd/9Q7SfsxqGIkXzGaMjuV8bIZAiBYsoK57eRqIvpYKUat+wa/dKCoSzPoenmf1Of9TliKmw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73274},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"4b3ceb0633cd73646a4d091ad282d4fd5e794360","scripts":{"test":"node --test test/**/*.test.js","build":"tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"","watch":"tsc --watch","prepare":"npm run build","inspector":"npx @modelcontextprotocol/inspector build/index.js","test:smoke":"node test/smoke.test.js"},"_npmUser":{"name":"hieuda","email":"anhhieudoan.work@gmail.com"},"repository":{"url":"git+https://github.com/HieuAnh87/sentry-selfhosted-mcp.git","type":"git"},"_npmVersion":"11.6.2","description":"Model context protocol server for self-hosted Sentry instances with debugging tools.","directories":{},"_nodeVersion":"25.2.1","dependencies":{"axios":"^1.8.4","@modelcontextprotocol/sdk":"0.6.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.3","@types/node":"^20.11.24"},"_npmOperationalInternal":{"tmp":"tmp/selfhosted-sentry-mcp_1.1.0_1767674393481_0.11473463413882956","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Security: raw_sentry_api can send your Sentry auth token to arbitrary hosts. Upgrade to >=1.2.0 and rotate the token."},"1.1.1":{"name":"selfhosted-sentry-mcp","version":"1.1.1","keywords":["mcp","modelcontextprotocol","sentry","self-hosted","debugging"],"author":{"name":"hieuda"},"license":"MIT","_id":"selfhosted-sentry-mcp@1.1.1","maintainers":[{"name":"hieuda","email":"anhhieudoan.work@gmail.com"}],"homepage":"https://github.com/HieuAnh87/sentry-selfhosted-mcp","bugs":{"url":"https://github.com/HieuAnh87/sentry-selfhosted-mcp/issues"},"bin":{"selfhosted-sentry-mcp":"build/index.js"},"dist":{"shasum":"ce02caaba17a5f3fe01e79a5f3c0de6df0adfbd3","tarball":"https://registry.npmjs.org/selfhosted-sentry-mcp/-/selfhosted-sentry-mcp-1.1.1.tgz","fileCount":4,"integrity":"sha512-n9ULHdAL+TdJ94KbcnwXGZfxZ4M55LpXJiCe8808YqwK6ik/MoA+XoF/ZJMb/Z8rQhSnQSlk1Yp+mZaP4oFl4w==","signatures":[{"sig":"MEQCIEejhkbVVQ7Zes7uGkGoOGde8Zfb1Wklm2i4piVLJ/x0AiAYGEmAVHVPPlT+PMuuzEYJPUuLGO3x1beaXttbTMupPA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73432},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"ecee6c9be73b92f67390fa1a696d5b52e6f72ee7","scripts":{"test":"node --test test/**/*.test.js","build":"tsc && node -e \"const fs=require('fs'); const content=fs.readFileSync('build/index.js','utf8'); fs.writeFileSync('build/index.js','#!/usr/bin/env node\\n'+content); fs.chmodSync('build/index.js','755');\"","watch":"tsc --watch","prepare":"npm run build","inspector":"npx @modelcontextprotocol/inspector build/index.js","test:smoke":"node test/smoke.test.js"},"_npmUser":{"name":"hieuda","email":"anhhieudoan.work@gmail.com"},"repository":{"url":"git+https://github.com/HieuAnh87/sentry-selfhosted-mcp.git","type":"git"},"_npmVersion":"11.6.2","description":"Model context protocol server for self-hosted Sentry instances with debugging tools.","directories":{},"_nodeVersion":"25.2.1","dependencies":{"axios":"^1.8.4","@modelcontextprotocol/sdk":"0.6.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.3","@types/node":"^20.11.24"},"_npmOperationalInternal":{"tmp":"tmp/selfhosted-sentry-mcp_1.1.1_1767674449230_0.5735756046921014","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Security: raw_sentry_api can send your Sentry auth token to arbitrary hosts. Upgrade to >=1.2.0 and rotate the token."},"1.1.2":{"name":"selfhosted-sentry-mcp","version":"1.1.2","keywords":["mcp","modelcontextprotocol","sentry","self-hosted","debugging"],"author":{"name":"hieuda"},"license":"MIT","_id":"selfhosted-sentry-mcp@1.1.2","maintainers":[{"name":"hieuda","email":"anhhieudoan.work@gmail.com"}],"homepage":"https://github.com/HieuAnh87/sentry-selfhosted-mcp","bugs":{"url":"https://github.com/HieuAnh87/sentry-selfhosted-mcp/issues"},"bin":{"selfhosted-sentry-mcp":"build/index.js"},"dist":{"shasum":"2ba2431b3071637eb2555d9ff3baa7806528e9ea","tarball":"https://registry.npmjs.org/selfhosted-sentry-mcp/-/selfhosted-sentry-mcp-1.1.2.tgz","fileCount":4,"integrity":"sha512-IxlkqKtR6cHE8wJIXDV2zIwrhSNbIRuUEAGJm+L+L6lP6FL38/K2WcYhGDGqHCStXIvKR2zsgaQW5W5P6nOq6Q==","signatures":[{"sig":"MEUCIQCQr2GKMShJ3t4C6kDwkcmhJCYjSaZt4PHZEXtCbnt7KAIgCqZgH17FQtNH8FbmUjZLCcXCvJMqV/9gPHMqnf/gauk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73862},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"7fe8741b4d8e8f7b671cfa5ce367092163dfa833","scripts":{"test":"node --test test/**/*.test.js","build":"tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"","watch":"tsc --watch","prepare":"npm run build","inspector":"npx @modelcontextprotocol/inspector build/index.js","test:smoke":"node test/smoke.test.js"},"_npmUser":{"name":"hieuda","email":"anhhieudoan.work@gmail.com"},"repository":{"url":"git+https://github.com/HieuAnh87/sentry-selfhosted-mcp.git","type":"git"},"_npmVersion":"11.6.2","description":"Model context protocol server for self-hosted Sentry instances with debugging tools.","directories":{},"_nodeVersion":"25.2.1","dependencies":{"axios":"^1.8.4","@modelcontextprotocol/sdk":"0.6.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.3","@types/node":"^20.11.24"},"_npmOperationalInternal":{"tmp":"tmp/selfhosted-sentry-mcp_1.1.2_1767685987301_0.9294651514862691","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Security: raw_sentry_api can send your Sentry auth token to arbitrary hosts. Upgrade to >=1.2.0 and rotate the token."},"1.2.0":{"name":"selfhosted-sentry-mcp","version":"1.2.0","keywords":["mcp","modelcontextprotocol","sentry","self-hosted","debugging"],"author":{"name":"hieuda"},"license":"MIT","_id":"selfhosted-sentry-mcp@1.2.0","maintainers":[{"name":"hieuda","email":"anhhieudoan.work@gmail.com"}],"homepage":"https://github.com/HieuAnh87/sentry-selfhosted-mcp","bugs":{"url":"https://github.com/HieuAnh87/sentry-selfhosted-mcp/issues"},"bin":{"selfhosted-sentry-mcp":"build/index.js"},"dist":{"shasum":"6399e4f5429ea2a949d919747567ecedd5896d2b","tarball":"https://registry.npmjs.org/selfhosted-sentry-mcp/-/selfhosted-sentry-mcp-1.2.0.tgz","fileCount":21,"integrity":"sha512-SrmiPC8MiEbDYbPQ5hCO/3fZLH1BIslPRi0W0IMf/e63hVmVkJzieC67DOQHzTTR6QKIYGaZEQMUq6ivy3KjfA==","signatures":[{"sig":"MEYCIQCra1kEZHIavqAKY+bJq2YNCQQl0u4uuMhsJOFa/3dsKAIhAKyYiTrUNPDEBoqUEWywuJYWcN6RLFaY7Iz8Y44kVfBk","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQCj1sYxeAn4eOqZniT+tjcVi6TiWDVdLdWSB0OHW7zg+QIhAOP9FjTKqk3kGWxzj/AcCwOeC2xA/MP4Mk3iL4xtSK9U","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":213180},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"9abe2ada10ba17b15fcfe90178301cccff77b46d","scripts":{"test":"node --test","build":"tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"","watch":"tsc --watch","prepare":"npm run build","pretest":"npm run build","inspector":"npx @modelcontextprotocol/inspector build/index.js","test:smoke":"node test/smoke.test.js"},"_npmUser":{"name":"hieuda","email":"anhhieudoan.work@gmail.com"},"repository":{"url":"git+https://github.com/HieuAnh87/sentry-selfhosted-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"Model context protocol server for self-hosted Sentry instances with debugging tools.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"axios":"^1.20.0","@modelcontextprotocol/sdk":"1.32.1"},"_hasShrinkwrap":false,"devDependencies":{"nock":"^14.0.10","typescript":"^5.3.3","@types/node":"^20.11.24"},"_npmOperationalInternal":{"tmp":"tmp/selfhosted-sentry-mcp_1.2.0_1792407220443_0.10669529850309489","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-01-06T03:48:21.611Z","modified":"2026-10-19T10:53:59.693Z","1.0.0":"2026-01-06T03:48:21.759Z","1.1.0":"2026-01-06T04:39:53.624Z","1.1.1":"2026-01-06T04:40:49.397Z","1.1.2":"2026-01-06T07:53:07.424Z","1.2.0":"2026-10-19T10:53:40.536Z"},"bugs":{"url":"https://github.com/HieuAnh87/sentry-selfhosted-mcp/issues"},"author":{"name":"hieuda"},"license":"MIT","homepage":"https://github.com/HieuAnh87/sentry-selfhosted-mcp","keywords":["mcp","modelcontextprotocol","sentry","self-hosted","debugging"],"repository":{"url":"git+https://github.com/HieuAnh87/sentry-selfhosted-mcp.git","type":"git"},"description":"Model context protocol server for self-hosted Sentry instances with debugging tools.","maintainers":[{"name":"hieuda","email":"anhhieudoan.work@gmail.com"}],"readme":"# selfhosted-sentry-mcp\n\n[![npm version](https://badge.fury.io/js/selfhosted-sentry-mcp.svg)](https://www.npmjs.com/package/selfhosted-sentry-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Model Context Protocol](https://img.shields.io/badge/MCP-2024--11--05-blue.svg)](https://modelcontextprotocol.io)\n\nMCP server that gives AI coding agents **token-efficient** access to a self-hosted Sentry instance.\n\n## Why this exists\n\nA single Sentry event endpoint can return well over 100,000 tokens — more than most models can hold, let alone reason about. Pointing an agent at the raw Sentry API usually ends in a blown context window.\n\nThis server is built around that problem:\n\n- **Compact by default.** `get_sentry_issue` returns essential fields only; `list_issue_events`, `list_error_events` and `get_release_details` return summaries unless you pass `full: true`. `get_sentry_event_details` returns 5 prioritized entries by default and strips heavy blocks (`sdk`, `packages`, `contexts`, `user`, `request`, `environment`), flagging each removal.\n- **A token budget.** List and detail tools measure their responses against a 50,000-token budget (`MAX_TOKENS` in `src/config.ts`) and truncate oversized ones with a hint instead of dumping them. The budget is a backstop, not a guarantee — narrow with filters, `grep_pattern` and pagination rather than relying on it.\n- **A refusal path.** If `raw_sentry_api` would return more than 50,000 tokens and you did not pass a `grep_pattern`, it refuses and returns grep suggestions rather than flooding the conversation.\n- **Filters on the way out.** Whitelist/blacklist field selection, regex grep, and stack-frame truncation — see [FILTERING.md](FILTERING.md).\n- **Purpose-built extractors.** `get_stack_frames`, `list_breadcrumbs` and `check_dsym_status` pull the debugging signal out of an event so the agent never sees the surrounding noise.\n\n## Quickstart\n\nNode.js 20+ and a self-hosted Sentry instance (Sentry SaaS also works if the token and org slug are valid).\n\n### 1. Create a Sentry auth token\n\n**Settings → Auth Tokens → Create New Token.**\n\nFor read-only use, select `event:read`, `org:read`, `project:read`, `team:read` and `project:releases`. Add `event:write` only if you want the four write tools.\n\nWhich scope each tool needs: [Token scopes](#token-scopes).\n\n### 2. Find your org slug\n\n**Settings → General** in your organization, or read it out of the URL: `https://your-sentry.com/organizations/[slug]/`.\n\n### 3. Install\n\n> **Use 1.2.0 or later.** Every earlier version is deprecated: its `raw_sentry_api` accepted absolute URLs and sent your Sentry auth token to them, and it has no `SENTRY_READ_ONLY`. If you ran an earlier version with an agent that reads Sentry data, rotate the token. The examples use `selfhosted-sentry-mcp@latest` so `npx` checks for the newest release instead of reusing an older copy from its cache. Check what you have with `npm ls -g selfhosted-sentry-mcp`.\n\n**Nothing to install.** The recommended setup runs the published package through `npx` straight from your MCP client config — skip to [Client configuration](#client-configuration).\n\nTo install it globally anyway:\n\n```bash\nnpm install -g selfhosted-sentry-mcp@latest\n```\n\nFrom source:\n\n```bash\ngit clone https://github.com/HieuAnh87/sentry-selfhosted-mcp.git\ncd sentry-selfhosted-mcp\nnpm install\nnpm run build\n```\n\n> The npm package is **`selfhosted-sentry-mcp`**. The GitHub repository is `HieuAnh87/sentry-selfhosted-mcp` — the two names are transposed. `sentry-selfhosted-mcp` on npm is an unrelated package by a different maintainer; do not install it and do not give it your token.\n\n## Configuration\n\n### Environment variables\n\n| Variable | Required | Default | Purpose |\n| --- | --- | --- | --- |\n| `SENTRY_URL` | yes | — | Base URL of your Sentry instance, e.g. `https://sentry.example.com`. Must be a valid URL; a trailing slash is stripped. |\n| `SENTRY_AUTH_TOKEN` | yes | — | Sentry API token. See [Token scopes](#token-scopes) below. |\n| `SENTRY_ORG_SLUG` | yes | — | Organization slug, e.g. `my-org`. |\n| `SENTRY_READ_ONLY` | no | `false` | Set to `true` (or `1`) to block writes. **Off by default** for backward compatibility, so write tools are exposed unless you opt in. See below for exactly what it blocks. Requires 1.2.0 or later — see the [version note](#3-install). |\n\nThe server validates the three required variables at startup and exits immediately if any is missing or if `SENTRY_URL` is not a valid URL.\n\n#### What `SENTRY_READ_ONLY=true` blocks\n\n| | Behaviour in read-only mode |\n| --- | --- |\n| `update_sentry_issue_status`, `create_sentry_issue_comment`, `bulk_update_issues`, `merge_issues` | Refused outright with an `InvalidRequest` error |\n| `raw_sentry_api` | Still available, but **`POST`, `PUT` and `DELETE` are refused**. `GET` continues to work. |\n| The other 23 tools | Unaffected |\n\nAccepted truthy values are `true` and `1` (case-insensitive). Anything else, including unset, leaves the server writable. When enabled, the startup line on stderr ends with `(read-only)`.\n\n### Token scopes\n\nSentry's scope namespaces are `org:*`, `project:*`, `team:*`, `member:*` and `event:*`. There is no `issue:*` or `comment:*` scope — issue and comment endpoints live under `event:*`.\n\n**Read-only setup** — covers 24 of the 28 tools (everything except the four write tools):\n\n| Scope | Needed by |\n| --- | --- |\n| `event:read` | Every issue and event tool: `get_sentry_issue`, `list_sentry_issues`, `list_issues`, `get_issue_hashes`, `get_sentry_event_details`, `list_issue_events`, `list_error_events`, `get_stack_frames`, `check_dsym_status`, `list_breadcrumbs`, `get_issue_tags`, `get_issue_tag_values`, `list_activity` (`issues/{id}/activities/`), `get_grouping_config` (reads the issue's latest event), `get_trace_details` (`organizations/{org}/trace/{id}/`, falling back to `events-trace/{id}/` — organization *events* endpoints, gated on `event:read` rather than `org:read`), `list_event_attachments`, `get_event_attachment` (attachments may also require the organization's attachments access role), `list_user_feedback` |\n| `org:read` | `list_sentry_projects`, `list_teams`, `list_releases` (organization-level endpoints) |\n| `project:read` | `list_sentry_projects`; `get_grouping_config` (`projects/{org}/{project}/events/{id}/grouping-info/`) |\n| `team:read` | `list_teams` |\n| `project:releases` | `list_releases`, `get_release_details` (grants both project and organization release endpoints) |\n\n**Add only if you want the write tools:**\n\n| Scope | Needed by |\n| --- | --- |\n| `event:write` | `update_sentry_issue_status`, `create_sentry_issue_comment`, `bulk_update_issues` and `merge_issues` (both `PUT projects/{org}/{project}/issues/?id=…`) |\n\n`raw_sentry_api` is bounded only by the token: it can call any endpoint your scopes permit, with `GET`, `POST`, `PUT` or `DELETE`. Scope the token to what you actually need — see [SECURITY.md](SECURITY.md).\n\n### Client configuration\n\nWhere the config file goes:\n\n| Client | Location |\n| --- | --- |\n| **Claude Code** (project) | `.mcp.json` at the repository root |\n| **Claude Code** (user) | `claude mcp add --scope user` — do not hand-edit `settings.json`, it does not read `mcpServers` |\n| **Cursor** | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) |\n\n**Option 1: npx (simplest)**\n\n```json\n{\n  \"mcpServers\": {\n    \"sentry\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"selfhosted-sentry-mcp@latest\"],\n      \"env\": {\n        \"SENTRY_URL\": \"https://your-sentry-instance.com\",\n        \"SENTRY_AUTH_TOKEN\": \"your-auth-token\",\n        \"SENTRY_ORG_SLUG\": \"your-org-slug\",\n        \"SENTRY_READ_ONLY\": \"true\"\n      }\n    }\n  }\n}\n```\n\nFor Claude Code's `.mcp.json` you may also add `\"type\": \"stdio\"` alongside `command`.\n\n> `SENTRY_READ_ONLY` needs 1.2.0 or later; earlier versions ignore it silently — see the [version note](#3-install).\n\nTo register it at user scope instead, without writing a config file by hand:\n\n```bash\nclaude mcp add --env SENTRY_URL=https://your-sentry-instance.com \\\n  --env SENTRY_AUTH_TOKEN=your-auth-token \\\n  --env SENTRY_ORG_SLUG=your-org-slug \\\n  --env SENTRY_READ_ONLY=true \\\n  --transport stdio --scope user sentry \\\n  -- npx -y selfhosted-sentry-mcp@latest\n```\n\n**Option 2: global npm install**\n\n```json\n{\n  \"mcpServers\": {\n    \"sentry\": {\n      \"command\": \"selfhosted-sentry-mcp\",\n      \"args\": [],\n      \"env\": {\n        \"SENTRY_URL\": \"https://your-sentry-instance.com\",\n        \"SENTRY_AUTH_TOKEN\": \"your-auth-token\",\n        \"SENTRY_ORG_SLUG\": \"your-org-slug\"\n      }\n    }\n  }\n}\n```\n\n**Option 3: local source build**\n\n```json\n{\n  \"mcpServers\": {\n    \"sentry\": {\n      \"command\": \"node\",\n      \"args\": [\"<full/path/to/sentry-selfhosted-mcp/build/index.js>\"],\n      \"env\": {\n        \"SENTRY_URL\": \"https://your-sentry-instance.com\",\n        \"SENTRY_AUTH_TOKEN\": \"your-auth-token\",\n        \"SENTRY_ORG_SLUG\": \"your-org-slug\"\n      }\n    }\n  }\n}\n```\n\n> These files contain a live Sentry token in plaintext. Keep them out of version control — see [SECURITY.md](SECURITY.md).\n\n### Verify it works\n\nConfirm the server starts and lists its tools before wiring it into a client:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | \\\n  SENTRY_URL=https://your-sentry-instance.com \\\n  SENTRY_AUTH_TOKEN=your-auth-token \\\n  SENTRY_ORG_SLUG=your-org-slug \\\n  npx -y selfhosted-sentry-mcp@latest\n```\n\nYou should see a JSON response listing 28 tools, plus a startup line on stderr naming your org slug and Sentry URL. (Fewer than 28 means an outdated version — see the [version note](#3-install). For a source build, replace `npx -y selfhosted-sentry-mcp@latest` with `node build/index.js`.)\n\n```\nSelf-hosted Sentry MCP server v… running for org \"your-org-slug\" at https://your-sentry-instance.com\n```\n\nIf the process exits instead, one of the three required environment variables is missing or `SENTRY_URL` is malformed.\n\nOr drive it interactively with the MCP inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector npx -y selfhosted-sentry-mcp@latest\n```\n\n## Usage\n\nOnce the server is registered, talk to your agent normally. Prompts that map cleanly onto these tools:\n\n- *\"List unresolved production issues in the `checkout` project, most frequent first.\"* → `list_issues` with `query: \"is:unresolved environment:production\"`, `sort: \"freq\"`\n- *\"Show me the in-app stack frames for event `abc123` in `apple-ios`.\"* → `get_stack_frames` with `in_app_only: true`\n- *\"What happened right before issue 5217 crashed?\"* → `list_issue_events` with `issue_id: \"5217\"`, `limit: 1` to get the latest event ID, then `list_breadcrumbs` with that `event_id` and the issue's `project_slug`\n- *\"Are we missing dSYMs for the iOS project?\"* → `check_dsym_status`\n- *\"Why are issues 4821 and 4822 grouped separately?\"* → `get_issue_hashes` and `get_grouping_config`\n- *\"Which OS versions does issue 5217 affect?\"* → `get_issue_tags`, then `get_issue_tag_values` with `tag_key: \"os.name\"`\n\nIf a response comes back truncated, narrow it rather than asking for more — pass `entry_type`, `limit`, `grep_pattern` or `max_stack_frames`, or page with `cursor`. See [Reducing response size](#reducing-response-size).\n\n## Tools\n\n28 tools across 8 categories. Parameters are **required** unless marked *optional*.\n\n**WRITE** marks the five tools that can modify Sentry. Under `SENTRY_READ_ONLY=true` the four dedicated write tools are hidden from the tool list and refused if called anyway, while `raw_sentry_api` stays available with `GET` only. Every tool also carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`), so clients can decide which calls need confirmation — see [Configuration](#what-sentry_read_onlytrue-blocks).\n\n**Issue IDs.** Every `issue_id` parameter accepts either a numeric ID (`5217`) or a short ID as shown in the Sentry UI (`PROJ-1A2`). `get_sentry_issue` also accepts a full issue URL.\n\n**Pagination.** Tools that take a `cursor` return, when Sentry has more results, a **second** text content block after the main result:\n\n```json\n{\"next_cursor\": \"0:25:0\", \"has_more\": true, \"hint\": \"More results exist. Call this tool again with cursor set to next_cursor.\"}\n```\n\nCall the same tool again with `cursor` set to `next_cursor` to get the next page. When there is no further page, the block is absent. The first block keeps its existing shape, so clients that only read `content[0]` are unaffected.\n\n> **Write tools act on real data.** `bulk_update_issues` requires a non-empty `query` or an `issue_ids` list and refuses to run without one — with no selection, Sentry would apply the change to every unresolved issue in the project (up to 1000). A broad `query` can still match hundreds of issues; check it with `list_sentry_issues` first. `merge_issues` cannot be undone.\n\n### Issue tools\n\n| Tool | Purpose | Parameters |\n| --- | --- | --- |\n| `get_sentry_issue` | Issue details by numeric ID, short ID or URL | `issue_id_or_url`; *optional* `include_latest_event` (default `false`), `include_fields[]`, `exclude_fields[]`, `grep_pattern`, `max_stack_frames` — see [FILTERING.md](FILTERING.md) |\n| `list_sentry_projects` | All projects in the org | *optional* `cursor` |\n| `list_sentry_issues` | Issues in one project, as compact triage fields (id, shortId, title, level, status, counts, first/last seen, project, assignee, error type/value) | `project_slug`; *optional* `query`, `status` (`resolved`/`unresolved`/`ignored`), `limit` (1–100, default 25), `cursor`, `full` (Sentry's full issue objects with stats) |\n| `list_issues` | Org-wide issue search, Sentry query syntax; compact fields like `list_sentry_issues` | *optional* `query`, `sort` (`date`/`priority`/`freq`/`user`, default `date`), `limit` (1–100, default 25), `cursor`, `full` |\n| `get_issue_hashes` | Fingerprint hashes for an issue | `issue_id`; *optional* `cursor` |\n| `update_sentry_issue_status` **WRITE** | Set issue status | `issue_id`, `status` (`resolved`/`ignored`/`unresolved`) |\n| `create_sentry_issue_comment` **WRITE** | Add a comment | `issue_id`, `comment_text` |\n| `bulk_update_issues` **WRITE** | Mass resolve/ignore/assign by query or ID list | `project_slug`, plus a non-empty `query` **or** `issue_ids[]` (numeric IDs, max 100); *optional* `status`, `assigned_to`, `has_seen`. **Refused if neither `query` nor `issue_ids` is given** — Sentry would otherwise apply the change to every unresolved issue in the project (up to 1000). |\n\n### Event tools\n\n| Tool | Purpose | Parameters |\n| --- | --- | --- |\n| `get_sentry_event_details` | Event details, entry-filtered | `project_slug`, `event_id`; *optional* `limit` (default 5), `offset` (default 0), `entry_type` (`exception`/`message`/`breadcrumbs`/`request`/`threads`/`debugmeta`/`contexts`). **`limit` is the main defence against token blowups.** Without `entry_type`, entries are prioritized `exception` → `message` → `breadcrumbs` → `request`. |\n| `list_issue_events` | Events for one issue over time | `issue_id`; *optional* `limit` (1–100, default 25), `cursor`, `full` (default `false`) |\n| `list_error_events` | Search events in a project | `project_slug`; *optional* `limit` (1–100, default 25), `cursor`, `query`, `full` (default `false`) |\n| `get_stack_frames` | Structured stack frames | `project_slug`, `event_id`; *optional* `in_app_only` (default `false`; keeps only frames Sentry marks as application code), `max_frames` (1–100, default 50; keeps the last N) |\n| `check_dsym_status` | Missing iOS/macOS dSYMs and ProGuard mappings | `project_slug`; *optional* `event_id`. Without it, checks the latest event of the first issue Sentry returns for the project — not necessarily the project's most recent event, so pass `event_id` when you have one. |\n| `list_breadcrumbs` | Trail of events before the error | `project_slug`, `event_id` (an event ID, not an issue ID — get one from `list_issue_events`); *optional* `limit` (1–100, default 50; returns the **most recent** N breadcrumbs), `type` (e.g. `default`, `http`, `navigation`, `error`) |\n\n### Release tools\n\n| Tool | Purpose | Parameters |\n| --- | --- | --- |\n| `list_releases` | Releases in the org | *optional* `query` (matches on version), `date` (**adoption status**, not a date: `adopted` or `unadopted`), `limit` (1–100, default 25), `cursor`, `sort` (`date`/`semver`, default `date`) |\n| `get_release_details` | Release details and health stats | `version`; *optional* `full` (default `false`; compact view omits stats) |\n\n### Organization tools\n\n| Tool | Purpose | Parameters |\n| --- | --- | --- |\n| `list_teams` | All teams in the org | none |\n| `get_issue_tags` | Tags captured for an issue | `issue_id` (returns the top 5 values per tag) |\n| `get_issue_tag_values` | Value distribution for one tag | `issue_id`, `tag_key`; *optional* `limit` (1–100, default 10) |\n| `list_activity` | Issue activity log | `issue_id`; *optional* `limit` (1–100, default 25), `cursor` |\n\n### Advanced tools\n\n| Tool | Purpose | Parameters |\n| --- | --- | --- |\n| `get_trace_details` | Distributed trace with spans | `trace_id`; *optional* `max_spans` (1–500, default 100). Requires Performance data. Uses Sentry's trace endpoint and falls back to `events-trace` on older self-hosted versions. |\n| `get_grouping_config` | Why the issue's latest event was grouped the way it was: grouping variants, their hashes and the components that contributed | `issue_id` |\n| `merge_issues` **WRITE** | Merge issues into one | `issue_id`, `target_ids[]` — **maximum 10**. More than 10 is rejected with an invalid-params error, not truncated. All issues must be error issues in the same project. **Sentry picks the surviving parent** (the earliest first seen), which may not be `issue_id`; the result reports the actual `parent` and `children`, and `merged: false` when Sentry did not confirm the merge. Merging is not reversible. |\n\n### Attachment and feedback tools\n\n| Tool | Purpose | Parameters |\n| --- | --- | --- |\n| `list_event_attachments` | Files the SDK attached to events: log files, minidumps, screenshots, view hierarchies | *either* `issue_id` (all attachments on the issue) *or* `project_slug` + `event_id`; *optional* `limit` (1–100, default 25), `cursor` |\n| `get_event_attachment` | Contents of a text attachment such as a log file | `project_slug`, `event_id`, `attachment_id`; *optional* `grep_pattern` (matching lines with context, across the whole file), `max_chars` (1–100,000, default 20,000 — the **end** of the file is kept, since that is usually nearest the crash). Binary attachments (minidumps, images) and files over 5 MB return metadata only; files Sentry serves from external storage via a redirect are not fetched with your token. |\n| `list_user_feedback` | What end users wrote when reporting a crash (Sentry user reports) | *either* `issue_id` *or* `project_slug`; *optional* `limit` (1–100, default 25), `cursor`. Reporter emails are omitted. Feedback from Sentry's newer User Feedback widget is stored as issues — find it with `list_issues` and `query: \"issue.category:feedback\"`. |\n\n### Account tools\n\n| Tool | Purpose | Parameters |\n| --- | --- | --- |\n| `whoami` | Connection and token check: the user the token belongs to, its scopes, whether `SENTRY_ORG_SLUG` is reachable, and which tools those scopes rule out. Start here when other tools return 401/403. | none |\n\n### Raw API\n\n| Tool | Purpose | Parameters |\n| --- | --- | --- |\n| `raw_sentry_api` **WRITE** | Any Sentry API endpoint | `endpoint` (path without the `/api/0/` prefix); *optional* `method` (`GET`/`POST`/`PUT`/`DELETE`, default `GET`), `params`, `body`, `grep_pattern`. Refuses responses over 50,000 tokens unless `grep_pattern` is set. Under `SENTRY_READ_ONLY=true` only `GET` is permitted. |\n\n## Reducing response size\n\n`get_sentry_issue` accepts five parameters that control response size — `include_latest_event`, `include_fields`, `exclude_fields`, `max_stack_frames` and `grep_pattern` — that exist specifically to keep large issues inside the token budget. `max_stack_frames` and any `latest_event.*` filter only have something to act on when `include_latest_event: true` is set.\n\n**[FILTERING.md](FILTERING.md) documents all of them with worked examples**, including the recommended escalation order when a response is still too big.\n\nQuick reference for the other tools:\n\n| Symptom | Fix |\n| --- | --- |\n| Event response truncated | `get_sentry_event_details` with `limit: 3` and `entry_type: \"exception\"` |\n| Only need the stack trace | `get_stack_frames` with `in_app_only: true` instead of the full event |\n| `raw_sentry_api` refuses to return | add a `grep_pattern` — it is required above 50k tokens |\n| Issue payload still too large | `max_stack_frames: 5`, then `exclude_fields`, then `include_fields`, then `grep_pattern` |\n| List result has more pages | read `next_cursor` from the second content block and pass it as `cursor` — see [Pagination](#tools) |\n\n## Docker\n\nBuild:\n\n```bash\ndocker build -t selfhosted-sentry-mcp:latest .\n```\n\nThe Docker image builds from your checkout, so it includes `SENTRY_READ_ONLY` and all 28 tools regardless of what is published on npm.\n\nClient config:\n\n```json\n{\n  \"mcpServers\": {\n    \"sentry\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"-e\", \"SENTRY_URL\",\n        \"-e\", \"SENTRY_AUTH_TOKEN\",\n        \"-e\", \"SENTRY_ORG_SLUG\",\n        \"-e\", \"SENTRY_READ_ONLY\",\n        \"selfhosted-sentry-mcp:latest\"\n      ],\n      \"env\": {\n        \"SENTRY_URL\": \"https://your-sentry-instance.com\",\n        \"SENTRY_AUTH_TOKEN\": \"your-auth-token\",\n        \"SENTRY_ORG_SLUG\": \"your-org-slug\",\n        \"SENTRY_READ_ONLY\": \"true\"\n      }\n    }\n  }\n}\n```\n\n`SENTRY_READ_ONLY` is optional: drop both of its lines to expose the write tools. Outside an MCP config, the equivalent `docker run` flag is `-e SENTRY_READ_ONLY=true`.\n\nUsing an env file keeps the token out of the config file entirely:\n\n```bash\n# /path/to/.env\nSENTRY_URL=https://your-sentry-instance.com\nSENTRY_AUTH_TOKEN=your-auth-token\nSENTRY_ORG_SLUG=your-org-slug\n# Optional: block write tools. Keep comments on their own line;\n# Docker does not strip trailing \"# ...\" from values.\nSENTRY_READ_ONLY=true\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"sentry\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"--env-file\", \"/path/to/.env\",\n        \"selfhosted-sentry-mcp:latest\"\n      ]\n    }\n  }\n}\n```\n\nVerify the image:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | docker run -i --rm \\\n  -e SENTRY_URL=https://example.com \\\n  -e SENTRY_AUTH_TOKEN=test \\\n  -e SENTRY_ORG_SLUG=test \\\n  selfhosted-sentry-mcp:latest\n```\n\n## Development\n\n```bash\nnpm install     # runs the build via the prepare hook\nnpm run build\nnpm test\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow. In short: `src/**` is the source of truth, `build/**` is generated and must never be edited by hand, and tool names and input schemas are a public contract.\n\nRun the MCP inspector against a local build:\n\n```bash\nnpx @modelcontextprotocol/inspector build/index.js\n```\n\n## Security\n\nThe server holds a live Sentry API token supplied as a plaintext environment variable, usually inside a config file that is easy to commit by accident.\n\n**Read [SECURITY.md](SECURITY.md) before deploying it.** It covers least-privilege token scoping, why `raw_sentry_api` bypasses least-privilege reasoning, the `SENTRY_READ_ONLY` switch, keeping tokens out of version control, and how to report a vulnerability.\n\n## Troubleshooting\n\n**Server not starting, or tools not showing**\n- Verify `SENTRY_URL`, `SENTRY_AUTH_TOKEN` and `SENTRY_ORG_SLUG` are all set. The server exits at startup if any is missing.\n- Confirm `SENTRY_URL` parses as a URL (include the scheme: `https://…`).\n- Check Node.js 20+: `node --version`.\n- On Claude Code, confirm the config is in `.mcp.json` or was added with `claude mcp add`. An `mcpServers` block in `settings.json` is ignored — the server will never load and there is no error.\n\n**\"Unauthorized\" or \"403\"**\n- The token is invalid, expired, or lacks the scope for that endpoint. Match the failing tool against the [scope table](#token-scopes).\n- Confirm the token belongs to the organization in `SENTRY_ORG_SLUG`.\n\n**\"Tool is disabled: server is running in read-only mode\"**\n- Expected if `SENTRY_READ_ONLY` is set to `true` or `1`. Unset it to restore write access. The startup line on stderr ends with `(read-only)` when the mode is active.\n\n**\"Project not found\"**\n- Confirm the slug exists; run `list_sentry_projects` to see the valid ones.\n\n**Empty or truncated responses**\n- Use `limit` and `entry_type` on `get_sentry_event_details`.\n- Use `grep_pattern` on `raw_sentry_api` for large endpoints.\n- See [Reducing response size](#reducing-response-size).\n\n**Docker container exits immediately**\n- All three required variables must reach the container. With `-e VAR` (no value) the variable must exist in your shell; otherwise use `--env-file`.\n- Check `docker logs <container-id>`.\n\n## FAQ\n\n**Is this self-hosted only?**\nIt targets self-hosted Sentry, but works against Sentry SaaS when the token and org slug are valid.\n\n**Why use `raw_sentry_api` when typed tools exist?**\nFor endpoints the typed tools do not cover. It returns unfiltered JSON, so pass `grep_pattern` on anything event-shaped — above 50,000 tokens it refuses outright without one.\n\n**Can I stop the agent from modifying Sentry?**\nSet `SENTRY_READ_ONLY=true` (requires 1.2.0 or later — see the [version note](#3-install)). That hides and refuses the four mutating tools and restricts `raw_sentry_api` to `GET`. For a stronger guarantee, issue a token without `event:write` — the env var stops an agent from calling the tool, the scope stops the credential from being usable at all.\n\n**Does it work with Sentry's newer API versions?**\nYes, for the versions in use today. Sentry has shipped only one public web API version — `/api/0/` — and every endpoint here is composed against it in `src/api/client.ts`. If Sentry ever publishes a `/api/1/`, this server would need updating.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}