npm package: @rui.branco/sentry-mcp
Description: Sentry MCP server for Claude Code - fetch issues, search errors, resolve/ignore issues, get stack traces and breadcrumbs
Author: Rui Branco
Latest version: 1.0.2

# Sentry MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that brings Sentry error tracking context directly into Claude Code. Fetch issues, inspect stack traces, manage issue status, and search errors without leaving your development environment.

## Overview

When debugging production errors, context switching between Sentry and your code editor breaks flow and wastes time. This MCP server solves that by:

- **Fetching full issue details** - Get error metadata, event counts, assignment, and status instantly
- **Inspecting stack traces** - View full stack traces with in-app frame markers, breadcrumbs, and HTTP request context
- **Managing issues** - Resolve, reopen, ignore, and assign issues directly from Claude Code
- **Searching errors** - Use Sentry's search syntax to find issues across your project

## Features

| Feature | Description |
|---------|-------------|
| Issue Details | Title, level, status, event count, user count, culprit, assignee |
| Stack Traces | Full exception chain with in-app frames highlighted |
| Breadcrumbs | Last N events leading up to the error |
| HTTP Request | Method, URL, headers from the request that triggered the error |
| Tags & Contexts | Device, browser, OS, user info, and custom tags |
| Search | Full Sentry search syntax support |
| Multi-Instance | Support for multiple Sentry organizations/instances |

## Installation

### Prerequisites

- Node.js 18+
- [Claude Code](https://claude.ai/code) CLI
- Sentry account with API access

### Step 1: Add to Claude Code

```bash
claude mcp add --transport stdio sentry -- npx -y @rui.branco/sentry-mcp
```

### Step 2: Get Your Sentry API Token

1. Go to [Sentry Auth Tokens](https://sentry.io/settings/account/api/auth-tokens/) (or your self-hosted Sentry equivalent)
2. Click **"Create New Token"**
3. Select scopes: `event:read`, `project:read`, `org:read`, `member:read`
4. Click **"Create Token"**
5. Copy the token

### Step 3: Configure Credentials

Run the setup with your credentials:

```bash
npx @rui.branco/sentry-mcp setup "YOUR_AUTH_TOKEN" "https://sentry.io" "your-org-slug" "your-project-slug"
```

| Parameter | Description | Example |
|-----------|-------------|---------|
| Auth Token | The token you created in Step 2 | `sntrys_eyJpYX...` |
| Base URL | Your Sentry instance URL | `https://sentry.io` or `https://my-org.sentry.io` |
| Org Slug | Your Sentry organization slug | `my-company` |
| Project Slug | Default project slug (optional) | `frontend` |

Or run interactively (will prompt for each value):

```bash
npx @rui.branco/sentry-mcp setup
```

### Step 4: Verify

Restart Claude Code and run `/mcp` to verify the server is connected.

### Alternative: Manual Installation

If you prefer to install manually:

```bash
git clone https://github.com/rui-branco/sentry-mcp.git ~/.config/sentry-mcp
cd ~/.config/sentry-mcp && npm install
node setup.js
```

Then add to Claude Code:

```bash
claude mcp add --transport stdio sentry -- node $HOME/.config/sentry-mcp/index.js
```

## Usage

### List Issues

```
> Show me unresolved Sentry issues

# Returns all unresolved issues with metadata
```

### Inspect an Error

```
> Get the latest event for Sentry issue 12345

# Returns full stack trace, breadcrumbs, HTTP request, tags, and contexts
```

### Resolve After Fixing

```
> Resolve Sentry issue 12345

# Marks the issue as resolved in Sentry
```

### Search Issues

```
> Search Sentry for "TypeError" errors in the last 24 hours

# Uses Sentry search: is:unresolved TypeError lastSeen:-24h
```

### Example Output

```
## Stack Trace

**TypeError:** Cannot read properties of undefined (reading 'map')

```
-> renderItems (src/components/List.tsx:42:15)
-> List (src/components/List.tsx:28:3)
   React.createElement (react-dom.js:1234)
```

## Breadcrumbs (last 5)

- **navigation** [info] /dashboard -> /items
- **http** [info] GET /api/items (200)
- **ui.click** [info] button.load-more
- **http** [error] GET /api/items?page=2 (500)
- **console** [error] Unhandled error in component

## HTTP Request

`GET /api/items?page=2`
```

## Multi-Instance Setup

For multiple Sentry organizations, add instances via setup:

```bash
npx @rui.branco/sentry-mcp setup add "work" "TOKEN_1" "https://sentry.io" "work-org" "work-project"
npx @rui.branco/sentry-mcp setup add "personal" "TOKEN_2" "https://sentry.io" "personal-org" "side-project"
```

Or via MCP tool at runtime:

```
> Add a new Sentry instance called "work" with org "my-company"
```

Use the `instance` parameter on any tool to target a specific instance, or omit it to use the default.

## API Reference

### Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `sentry_list_projects` | List all Sentry projects accessible by the token | `instance` |
| `sentry_get_issues` | Get unresolved issues for the configured project | `query`, `instance` |
| `sentry_get_issue` | Get full details for a specific issue | `issueId` (required), `instance` |
| `sentry_get_latest_event` | Get latest event with stack trace, breadcrumbs, HTTP request | `issueId` (required), `instance` |
| `sentry_resolve_issue` | Mark an issue as resolved | `issueId` (required), `instance` |
| `sentry_unresolve_issue` | Reopen a resolved issue | `issueId` (required), `instance` |
| `sentry_ignore_issue` | Ignore/snooze an issue | `issueId` (required), `instance` |
| `sentry_search_issues` | Search with custom Sentry query | `query` (required), `instance` |
| `sentry_assign_issue` | Assign an issue to a user or team | `issueId` (required), `assignee` (required), `instance` |
| `sentry_list_instances` | List all configured instances | none |
| `sentry_add_instance` | Add or update an instance at runtime | `name`, `token`, `baseUrl`, `orgSlug` (all required), `projectSlug`, `projects`, `setDefault` |
| `sentry_remove_instance` | Remove an instance | `name` (required) |

### Configuration

Config stored at `~/.config/sentry-mcp/config.json`:

```json
{
  "instances": [
    {
      "name": "work",
      "token": "YOUR_AUTH_TOKEN",
      "baseUrl": "https://sentry.io",
      "orgSlug": "my-company",
      "projectSlug": "frontend",
      "projects": ["frontend", "backend"]
    }
  ],
  "defaultInstance": "work"
}
```

## Security

- API tokens are stored locally in `~/.config/sentry-mcp/config.json`
- Config files are excluded from git via `.gitignore`
- Tokens are never logged or transmitted except to the Sentry API

## License

MIT

## Related

- [jira-mcp](https://github.com/rui-branco/jira-mcp) - Jira MCP server for Claude Code
- [figma-mcp](https://github.com/rui-branco/figma-mcp) - Figma MCP server for Claude Code
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification