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

Tool	Purpose	Input (summary)
get_sentry_issue	Issue details by ID or URL with optional latest event	issue_id_or_url + optional filters
list_sentry_projects	List all projects in org	{}
list_sentry_issues	List issues in a project with query/status	project_slug + optional query, status, limit, cursor
get_sentry_event_details	Event details with pagination and entry filtering	project_slug, event_id, optional entry_type, limit, offset
update_sentry_issue_status	Update issue status	issue_id, status
create_sentry_issue_comment	Add issue comment	issue_id, comment_text
raw_sentry_api	Raw Sentry API call with optional grep filter	endpoint + optional method, params, body, grep_pattern
get_stack_frames	Extract structured stack frames	project_slug, event_id, optional in_app_only, max_frames
check_dsym_status	Check missing dSYM symbols	project_slug, optional event_id
list_issue_events	List events for an issue	issue_id, optional limit, cursor, full
get_issue_hashes	Fetch fingerprint hashes for grouping	issue_id, optional cursor
list_error_events	Search error events in a project	project_slug, optional limit, cursor, query, full

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