# Sentry MCP Server

> **Forked from [elad12390/loki-mcp](https://github.com/elad12390/loki-mcp)** — retargeted from Grafana Loki to Sentry. Same "few sharp tools, no config" ergonomics, new backend. This repo keeps the original's git history.

An [MCP](https://github.com/modelcontextprotocol/protocol) server to easily search and analyze [Sentry](https://sentry.io) issues, events, and traces — without writing Sentry queries or clicking through the UI.

This is a focused, fast alternative to the official Sentry MCP: a small, predictable tool set modeled on a battle-tested log-search MCP, talking directly to the Sentry REST API.

## Quick Start

You can run this server directly using `npx`:

```bash
export SENTRY_AUTH_TOKEN="sntryu_..."      # Sentry auth token (see Configuration)
export SENTRY_URL="https://us.sentry.io"   # your region/host (default: https://sentry.io)
export SENTRY_ORG="my-org"                  # optional; auto-detected if omitted

npx @elad12390/sentry-mcp
```

## Features

This MCP server provides **4 tools**, **3 resources**, and **3 prompts**. AI assistants automatically understand when to use each based on natural language.

### Tools

**🔍 `sentry_search_issues`** — Your primary search tool
- Just say: "check sentry", "what's breaking", "show me errors", "unresolved issues", "top errors", "how many errors"
- Searches grouped issues across ALL projects automatically (or filter by `project`)
- Uses Sentry search syntax in `query` (`is:unresolved level:error`, `release:latest`, free text)
- Set `count=true` for event counts + an ASCII trend chart instead of the issue list

**🔗 `sentry_trace_lookup`** — Distributed tracing
- Just say: "follow this trace", "what happened in this request", "trace this id across services"
- Returns every span and error in a trace, grouped by service, as a timeline

**🔎 `sentry_get_issue_details`** — Root cause analysis
- Just say: "show the stack trace", "what happened before this error", "why did this fail"
- Returns the exception + stack trace, the **breadcrumbs** (what happened right before), request context, tags, and the trace ID

**🧩 `sentry_pattern_analysis`** — Group & rank error patterns
- Just say: "group similar errors", "what error types", "do we have one problem or many"
- Ranks issue groups by event volume and merges near-duplicate titles into higher-level patterns

### Resources (Read-only Data)

**`sentry://projects`** — List all projects in the org
- Read this first to know what you can filter by

**`sentry://tags`** — List all tag keys (searchable metadata)
- Shows what you can filter by (environment, release, browser, etc.)

**`sentry://tags/{key}/values`** — Get values for a specific tag
- Example: `sentry://tags/environment/values`

### Prompts (Guided Workflows)

**`debug-error`** — Search the issue, pull stack trace + breadcrumbs, gauge blast radius
- Arguments: `error_text` (required), `project`, `time_window`

**`trace-request`** — Follow a trace ID across services
- Arguments: `trace_id` (required), `time_window`

**`health-check`** — List projects, count errors + trend, find dominant patterns
- Arguments: `project`, `time_window`

## Usage Tips for AI Assistants

When the user says **"check sentry"** or **"what's broken"**, you should:

1. **Read `sentry://projects`** if you don't know what projects exist
2. **Use `sentry_search_issues`** as your primary tool — it works across all projects
3. **Follow up with `sentry_get_issue_details`** on an interesting issue for the stack trace + breadcrumbs
4. **Use `sentry_search_issues` with `count=true`** when they ask "how many" / "is it getting worse"
5. **Use `sentry_pattern_analysis`** during incidents to see if it's one problem or many

For complex debugging, use the **prompts**: `debug-error`, `trace-request`, `health-check`.

## Example Conversations

**User:** "Check sentry for errors in the python-fastapi project"
**AI:** *Uses `sentry_search_issues` with project="python-fastapi", query="is:unresolved"*

**User:** "How many errors happened today?"
**AI:** *Uses `sentry_search_issues` with count=true, time_window="24h"*

**User:** "Why is PYTHON-FASTAPI-TK failing?"
**AI:** *Uses `sentry_get_issue_details` with the issue id*

**User:** "Follow trace ce8f0d3961214198a040517b3dfda0d4"
**AI:** *Uses `sentry_trace_lookup`*

## Configuration

Set the following environment variables:

- `SENTRY_AUTH_TOKEN` (**required**): A Sentry auth token. Create one at **Settings → Auth Tokens** (organization token) or **User Settings → Personal Tokens**. Required scopes: `org:read`, `project:read`, `event:read`.
- `SENTRY_URL`: Base URL of your Sentry instance. Default `https://sentry.io`. SaaS users on a specific region should use `https://us.sentry.io`, `https://de.sentry.io`, etc. Self-hosted: your own host.
- `SENTRY_ORG`: Organization slug. Optional — if omitted, the first org the token can access is auto-detected.
- `SENTRY_PROJECT`: Default project slug used for tag-value lookups. Optional — defaults to the first project in the org.

## Development

```bash
bun install
bun run build
bun test
```

See [AGENTS.md](./AGENTS.md) for code style and contribution notes.