npm package: @peanutgghope/sentry-mcp-server
Description: Model Context Protocol server for Sentry - Provides event and issue tracking integration with AI assistants
Author: Wallace Wen
Latest version: 1.1.10

# Sentry MCP Server

[![npm version](https://badge.fury.io/js/@wallacewen%2Fsentry-mcp-server.svg)](https://badge.fury.io/js/@wallacewen%2Fsentry-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server that provides seamless integration with Sentry for error monitoring and event tracking. This server enables AI assistants like Claude to access Sentry data for debugging, error analysis, and monitoring insights.

## Features

- 🔍 **Query Sentry Events**: Retrieve error events and issues from your Sentry projects
- 📊 **Event Analysis**: Get detailed information about errors, including stack traces, user context, and metadata
- 🔄 **Pagination Support**: Handle large datasets with built-in pagination
- 🛡️ **Secure Authentication**: Support for Sentry API tokens with proper scope validation
- ⚙️ **Flexible Configuration**: Works with both Sentry.io and self-hosted Sentry instances
- 🚀 **Easy Integration**: Simple setup with Claude Desktop, Cline, and other MCP clients

## Installation

### Option 1: Global Installation (Recommended)
```bash
npm install -g @wallacewen/sentry-mcp-server
```

### Option 2: Use with npx (No installation required)
```bash
npx @wallacewen/sentry-mcp-server
```

## Quick Start

### 1. Get Your Sentry API Token

1. Go to [Sentry.io](https://sentry.io) (or your self-hosted instance)
2. Navigate to **Settings** → **API** → **Auth Tokens**
3. Create a new token with these scopes:
   - `project:read`
   - `event:read`
4. Copy the generated token

### 2. Configure Environment Variables

Create a `.env` file or set environment variables:

```env
SENTRY_BASE_URL=https://sentry.io/api/0
SENTRY_TOKEN=your_sentry_api_token_here
SENTRY_ORGANIZATION=your-org-slug
SENTRY_PROJECT=your-project-slug
```

### 3. Configure Your MCP Client

#### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["@wallacewen/sentry-mcp-server"],
      "env": {
        "SENTRY_BASE_URL": "https://sentry.io/api/0",
        "SENTRY_TOKEN": "your_sentry_api_token_here",
        "SENTRY_ORGANIZATION": "your-org-slug",
        "SENTRY_PROJECT": "your-project-slug"
      }
    }
  }
}
```

#### Other MCP Clients

See [ENVIRONMENT_SETUP.md](./ENVIRONMENT_SETUP.md) for detailed configuration instructions for Cline, VS Code, and other MCP clients.

## Usage

Once configured, you can interact with Sentry through your MCP client:

### Query Recent Errors

```
"Can you check the recent errors in my frontend project? Use project slug 'my-app' and look at the last 7 days."
```

### Analyze Specific Issues

```
"Show me the most recent 10 error events from the 'backend-api' project and help me understand the common patterns."
```

### Monitor Project Health

```
"Get the error events from the last 30 days for project 'mobile-app' and summarize the most critical issues."
```

## Available Tools

### `sentry_events`

Retrieve Sentry events and issues for analysis and debugging.

**Parameters:**
- `projectSlug` (required): The slug of your Sentry project
- `days` (optional): Number of days to look back (1-90, default: 30)
- `max_events` (optional): Maximum events to fetch (1-100, default: 20)
- `event_index` (optional): Starting index for pagination (default: 0)

**Example Response:**
```json
{
  "success": true,
  "message": "Sentry events retrieved successfully",
  "data": {
    "events": [
      {
        "id": "abc123",
        "title": "TypeError: Cannot read property 'name' of undefined",
        "level": "error",
        "dateCreated": "2025-01-20T10:30:00Z",
        "project": "my-app",
        "platform": "javascript",
        "environment": "production"
      }
    ],
    "paging": {
      "pageIndex": 0,
      "pageSize": 20,
      "total": 45
    }
  },
  "total_events": 1
}
```

## Configuration

### Environment Variables

| Variable | Required | Description | Default |
|----------|----------|-------------|---------|
| `SENTRY_BASE_URL` | Yes | Sentry API base URL | - |
| `SENTRY_TOKEN` | Yes | Sentry API authentication token | - |
| `SENTRY_ORGANIZATION` | No | Default organization slug | - |
| `SENTRY_PROJECT` | No | Default project slug | - |

### Sentry API URLs

- **Sentry.io**: `https://sentry.io/api/0`
- **Self-hosted**: `https://your-sentry-instance.com/api/0`

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/wallacewen/sentry-mcp-server.git
cd sentry-mcp-server

# Install dependencies
pnpm install

# Copy environment template
cp env.example .env
# Edit .env with your Sentry configuration

# Build the project
pnpm build

# Run tests
pnpm test

# Start development server
pnpm dev
```

### Project Structure

```
sentry-mcp-server/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── sentry.ts         # Sentry API client
│   └── types.ts          # TypeScript definitions
├── dist/                 # Compiled JavaScript
├── tests/                # Test files
└── docs/                 # Documentation
```

## Troubleshooting

### Common Issues

1. **Authentication Error (401)**
   - Verify your `SENTRY_TOKEN` is correct
   - Check token scopes include `project:read` and `event:read`

2. **Project Not Found (404)**
   - Confirm the `projectSlug` parameter is correct
   - Ensure your token has access to the project

3. **Connection Issues**
   - Verify `SENTRY_BASE_URL` is correct
   - For self-hosted instances, ensure server accessibility

### Debug Mode

Enable detailed logging:

```env
NODE_ENV=development
```

### Getting Help

- 📖 **Full Setup Guide**: [ENVIRONMENT_SETUP.md](./ENVIRONMENT_SETUP.md)
- 🚀 **Publishing Guide**: [PUBLISHING.md](./PUBLISHING.md)
- 🐛 **Report Issues**: [GitHub Issues](https://github.com/wallacewen/sentry-mcp-server/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/wallacewen/sentry-mcp-server/discussions)

## Contributing

We welcome contributions! Please see our [Contributing Guidelines](./CONTRIBUTING.md) for details.

### Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if needed
5. Run tests and linting
6. Submit a pull request

## Security

- Keep your Sentry API tokens secure
- Never commit sensitive information to version control
- Regularly rotate API tokens
- Use minimum required token scopes

## License

MIT License - see [LICENSE](./LICENSE) file for details.

## Related Projects

- [Model Context Protocol](https://github.com/modelcontextprotocol) - Core MCP framework
- [Claude Desktop](https://claude.ai) - AI assistant with MCP support
- [Sentry](https://sentry.io) - Error monitoring and performance tracking

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history and changes.

---

Made with ❤️ for the MCP and Sentry communities.