Metadata-Version: 2.4
Name: gfg-sentry-mcp-server
Version: 0.1.0
Summary: MCP server for querying Sentry alerts and issues.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: requests>=2.31.0

# Sentry MCP Server (Python)

This project provides a Python MCP server with tools for:

- list alerts
- retrieve alert detail (including rule payload)
- search issues
- retrieve an issue
- list issue events
- retrieve issue event

## Tools

1. `sentry_list_alert_rules`
   - Lists issue alert rules and/or metric alert rules.
2. `sentry_retrieve_alert_rule_detail`
   - Retrieves a single alert rule detail (`metric` or `issue`).
3. `sentry_search_issues`
   - Searches issues using Sentry query syntax.
   - Parameters:
     - `query` (required): Sentry issue search query.
     - `org_slug` (optional): overrides `SENTRY_ORG_SLUG`.
     - `limit` (optional): max results, clamped to `1..100` (default `25`).
   - Returns:
     - `organization`: organization slug used.
     - `query`: original query string.
     - `count`: number of issues in this response.
     - `issues`: raw issue objects from Sentry.
   - Notes:
     - This tool fetches one page of results only.
     - For large result sets, use narrower filters and run multiple queries.
4. `sentry_retrieve_issue`
   - Retrieves one issue by issue ID.
5. `sentry_list_issue_events`
   - Lists error events for a specific issue.
   - Parameters:
     - `issue_id` (required): global Sentry issue ID.
     - `org_slug` (optional): overrides `SENTRY_ORG_SLUG`.
     - `start` / `end` (optional): ISO-8601 time range.
     - `stats_period` (optional): relative range like `24h`, `7d` (overrides start/end).
     - `environment` (optional): one or more environment filters.
     - `full` (optional): include full event body payload (stacktrace/context).
     - `sample` (optional): deterministic pseudo-random event order.
     - `query` (optional): Sentry event search query.
     - `cursor` (optional): pagination cursor from Sentry response headers.
   - Returns:
     - `organization`: organization slug used.
     - `issue_id`: issue ID used.
     - `count`: number of events in this response.
     - `events`: raw event objects from Sentry.
6. `sentry_retrieve_issue_event`
   - Retrieves one specific issue event.
   - Parameters:
     - `issue_id` (required): global Sentry issue ID.
     - `event_id` (required): event ID, or `latest`, `oldest`, `recommended`.
     - `org_slug` (optional): overrides `SENTRY_ORG_SLUG`.
     - `environment` (optional): one or more environment filters.
   - Returns:
     - `organization`: organization slug used.
     - `issue_id`: issue ID used.
     - `event_id`: event identifier used.
     - `event`: raw event object from Sentry.

### `search_issues` query examples

Use Sentry issue search filters in the `query` field:

- `is:unresolved level:error`
- `environment:production release:1.2.3`
- `user.email:alice@example.com`
- `transaction:/api/orders has:stacktrace`
- `project:backend assigned:me`

## Required Environment Variables

- `SENTRY_AUTH_TOKEN`: Sentry token with sufficient read permissions.
- `SENTRY_ORG_SLUG`: Default organization slug (optional if always passed to tools).
- `SENTRY_BASE_URL`: Optional, defaults to `https://sentry.io/api/0`.

## Install

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Run

```bash
export SENTRY_AUTH_TOKEN="YOUR_TOKEN"
export SENTRY_ORG_SLUG="your-org"
sentry-mcp-server
```

## Example MCP config snippet

Use this in your MCP client configuration:

```json
{
  "mcpServers": {
    "sentry": {
      "command": "sentry-mcp-server",
      "env": {
        "SENTRY_AUTH_TOKEN": "YOUR_TOKEN",
        "SENTRY_ORG_SLUG": "your-org"
      }
    }
  }
}
```

## Publish to PyPI

This repository includes `.github/workflows/publish-pypi.yml` for trusted publishing.

1. Create a release tag like `v0.1.1`.
2. Push the tag to GitHub.
3. GitHub Actions builds the package and publishes it to PyPI.

