selfhosted-sentry-mcp

MCP server for self-hosted Sentry instances with debugging-focused tools.

Overview

This server provides MCP tools for querying and triaging issues and events in self-hosted Sentry.

Key capabilities:

• Issue and project listing with pagination and search.
• Event inspection with stack frame extraction.
• Grouping analysis via issue hashes.
• Debug symbol (dSYM) checks for iOS/macOS crashes.
• Raw Sentry API access for edge cases.

Quickstart

Prerequisites

• Node.js 20+
• Self-hosted Sentry instance

Getting Sentry Credentials

You need 3 environment variables from your Sentry instance:

1. SENTRY_URL

https://your-sentry-instance.com

The base URL of your self-hosted Sentry.

2. SENTRY_AUTH_TOKEN

1. Go to Settings > Auth Tokens
2. Click Create New Token
3. Select scopes: issue:read, project:read, event:read, issue:write, comment:write
4. Copy the token

3. SENTRY_ORG_SLUG

1. Go to Settings > General in your organization
2. Find Organization Slug (e.g., my-org)
3. Or check the URL: https://your-sentry.com/organizations/[slug]/

Install

Option 1: Install from npm (recommended)

npm install -g selfhosted-sentry-mcp

Option 2: Install from source

git clone https://github.com/HieuAnh87/sentry-selfhosted-mcp.git
cd sentry-selfhosted-mcp
npm install
npm run build

Tools

24 tools available across 6 categories:

Issue Tools

| Tool | Purpose | Input | | --- | --- | --- | | get_sentry_issue | Issue details by ID or URL | issue_id_or_url + optional filters | | list_sentry_projects | List all projects in org | {} | | list_sentry_issues | List issues in a project | project_slug + optional filters | | list_issues | Search issues with Sentry query syntax | query, sort, limit, cursor | | update_sentry_issue_status | Update issue status | issue_id, status | | create_sentry_issue_comment | Add issue comment | issue_id, comment_text | | get_issue_hashes | Get fingerprint hashes | issue_id, optional cursor | | bulk_update_issues | Bulk resolve/ignore issues | project_slug + optional query, status, assigned_to, has_seen |

Event Tools

| Tool | Purpose | Input | | --- | --- | --- | | get_sentry_event_details | Event details with entry filtering | project_slug, event_id | | list_issue_events | List events for an issue | issue_id, optional limit, cursor, full | | list_error_events | Search error events in a project | project_slug + optional filters | | get_stack_frames | Extract structured stack frames | project_slug, event_id, in_app_only, max_frames | | check_dsym_status | Check missing dSYM symbols | project_slug, optional event_id | | list_breadcrumbs | Extract breadcrumbs from event | project_slug, event_id, optional limit, type |

Release Tools

| Tool | Purpose | Input | | --- | --- | --- | | list_releases | List releases in org | query, date, limit, cursor, sort | | get_release_details | Release details with health stats | version, optional full |

Organization Tools

| Tool | Purpose | Input | | --- | --- | --- | | list_teams | List all teams in org | {} | | get_issue_tags | List all tags for an issue | issue_id | | get_issue_tag_values | Get tag value distribution | issue_id, tag_key, optional limit | | list_activity | Issue activity log | issue_id, optional limit, cursor |

Advanced Tools

| Tool | Purpose | Input | | --- | --- | --- | | get_trace_details | Distributed trace with spans | trace_id, optional max_spans | | get_grouping_config | Fingerprinting rules | issue_id | | merge_issues | Merge issues by hash | issue_id, target_ids |

Raw API

| Tool | Purpose | Input | | --- | --- | --- | | raw_sentry_api | Any Sentry API endpoint | endpoint + optional method, params, body, grep_pattern |

Configuration

Set environment variables:

• SENTRY_URL: Base URL of your self-hosted Sentry instance.
• SENTRY_AUTH_TOKEN: Sentry API token (recommended scopes: issue:read, project:read, event:read, issue:write, comment:write).
• SENTRY_ORG_SLUG: Organization slug.

Claude Code / Cursor Configuration

Add to your MCP client configuration file:

• Claude Code: ~/.claude/settings.json or project-level .claude/settings.json
• Cursor: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-level)

Option 1: Using npx (recommended - simplest)

{
  "mcpServers": {
    "sentry-selfhosted-mcp": {
      "command": "npx",
      "args": ["-y", "selfhosted-sentry-mcp"],
      "env": {
        "SENTRY_URL": "https://your-sentry-instance.com",
        "SENTRY_AUTH_TOKEN": "your-auth-token",
        "SENTRY_ORG_SLUG": "your-org-slug"
      }
    }
  }
}

Option 2: Using global npm install

{
  "mcpServers": {
    "sentry-selfhosted-mcp": {
      "command": "selfhosted-sentry-mcp",
      "args": [],
      "env": {
        "SENTRY_URL": "https://your-sentry-instance.com",
        "SENTRY_AUTH_TOKEN": "your-auth-token",
        "SENTRY_ORG_SLUG": "your-org-slug"
      }
    }
  }
}

Option 3: From local source

{
  "mcpServers": {
    "sentry-selfhosted-mcp": {
      "command": "node",
      "args": ["<full/path/to/sentry-selfhosted-mcp/build/index.js>"],
      "env": {
        "SENTRY_URL": "https://your-sentry-instance.com",
        "SENTRY_AUTH_TOKEN": "your-auth-token",
        "SENTRY_ORG_SLUG": "your-org-slug"
      }
    }
  }
}

Docker

Build:

docker build -t sentry-selfhosted-mcp:latest .

Claude Code config:

{
  "mcpServers": {
    "sentry-selfhosted-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SENTRY_URL",
        "-e", "SENTRY_AUTH_TOKEN",
        "-e", "SENTRY_ORG_SLUG",
        "sentry-selfhosted-mcp:latest"
      ],
      "env": {
        "SENTRY_URL": "https://your-sentry-instance.com",
        "SENTRY_AUTH_TOKEN": "your-auth-token",
        "SENTRY_ORG_SLUG": "your-org-slug"
      }
    }
  }
}

Use env file:

SENTRY_URL=https://your-sentry-instance.com
SENTRY_AUTH_TOKEN=your-auth-token
SENTRY_ORG_SLUG=your-org-slug

{
  "mcpServers": {
    "sentry-selfhosted-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/path/to/.env",
        "sentry-selfhosted-mcp:latest"
      ]
    }
  }
}

Verify:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | docker run -i --rm \
  -e SENTRY_URL=https://example.com \
  -e SENTRY_AUTH_TOKEN=test \
  -e SENTRY_ORG_SLUG=test \
  sentry-selfhosted-mcp:latest

Development

npm install
npm run build

Run MCP inspector:

npx @modelcontextprotocol/inspector build/index.js

Security

• Use least-privilege Sentry API tokens.
• Avoid logging sensitive data in MCP client logs.

Troubleshooting

Server not starting or tools not showing:

• Verify SENTRY_URL, SENTRY_AUTH_TOKEN, and SENTRY_ORG_SLUG are set correctly.
• Check the token has required scopes (issue:read, project:read, event:read, issue:write, comment:write).
• Ensure Node.js 20+ is installed: node --version.

"Unauthorized" or "403" errors:

• Verify your Sentry API token is valid and not expired.
• Check that the token has permissions for the organization specified in SENTRY_ORG_SLUG.

"Project not found" errors:

• Confirm the project slug exists in your Sentry organization.
• Use list_sentry_projects tool to see available projects.

Empty or truncated responses:

• For event details, use limit parameter to paginate through large events.
• For raw_sentry_api, use grep_pattern to filter responses from large endpoints.

Docker container exits immediately:

• Ensure all three environment variables are passed: SENTRY_URL, SENTRY_AUTH_TOKEN, SENTRY_ORG_SLUG.
• Check Docker logs: docker logs <container-id>.

FAQ

Q: Is this server self-hosted only? A: It is designed for self-hosted Sentry, but it should also work with Sentry SaaS if the API token and org slug are valid.

Q: Why use raw_sentry_api if other tools exist? A: It exposes any API endpoint for edge cases not covered by typed tools. Use grep_pattern on event endpoints to keep responses small.

License

MIT