Sentry MCP Server

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)

npm install -g @wallacewen/sentry-mcp-server

Option 2: Use with npx (No installation required)

npx @wallacewen/sentry-mcp-server

Quick Start

1. Get Your Sentry API Token

1. Go to 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:

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:

{
  "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 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:

{
  "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

# 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:

NODE_ENV=development

Getting Help

• 📖 Full Setup Guide: ENVIRONMENT_SETUP.md
• 🚀 Publishing Guide: PUBLISHING.md
• 🐛 Report Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Contributing

We welcome contributions! Please see our Contributing Guidelines 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 file for details.

Related Projects

• Model Context Protocol - Core MCP framework
• Claude Desktop - AI assistant with MCP support
• Sentry - Error monitoring and performance tracking

Changelog

See CHANGELOG.md for version history and changes.

Made with ❤️ for the MCP and Sentry communities.