Bugsink MCP Server

A professional Model Context Protocol server for interacting with Bugsink error tracking via LLMs.

This server enables AI assistants like Claude, Cursor, Windsurf, and other MCP-compatible tools to deeply analyze your error tracking data. It goes beyond simple listing, offering "Smart Context" analysis to help LLMs solve bugs faster.

✨ Key Features

• 🔍 Smart Context Analysis: The analyze_issue_context tool retrieves the issue details, the latest 5 events, and their stacktraces in a single call, giving the LLM immediate holistic context to fix bugs without "chat ping-pong".
• 🌍 Multi-Language Support (i18n): Fully localized responses. Supports English (en) and Spanish (es) out of the box.
• ⚡ Advanced Event Filtering: Filter error events by Browser (e.g., "Chrome"), OS (e.g., "iOS"), or specific error messages directly from the MCP tool.
• 🧠 Stacktrace Intelligence: Retrieves pre-rendered Markdown stacktraces for better LLM readability.
• 🛠️ Full Management: Create and update Projects and Teams directly from your chat.

🚀 Installation

Via npx (Recommended)

To run it directly without installing:

npx @alvaroadlf/bugsink-mcp

Global Install

npm install -g @alvaroadlf/bugsink-mcp

From Source

git clone https://github.com/alvaroadlf/bugsink-mcp.git
cd bugsink-mcp
npm install
npm run build

⚙️ Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | BUGSINK_URL | Yes | Your Bugsink instance URL (e.g., https://error-tracking.example.com) | | BUGSINK_TOKEN | Yes | API token for authentication | | BUGSINK_LOCALE | No | Language code (en or es). Default: en |

Generating an API Token

1. Log in to your Bugsink instance.
2. Go to Settings > API Tokens.
3. Create a new token.

Or via CLI:

bugsink-manage create_auth_token

💻 Client Configuration

Claude Desktop / Antigravity

Add to your claude_desktop_config.json or antigravity_config.json:

{
  "mcpServers": {
    "bugsink": {
      "command": "npx",
      "args": ["@alvaroadlf/bugsink-mcp"],
      "env": {
        "BUGSINK_URL": "https://your-bugsink-instance.com",
        "BUGSINK_TOKEN": "your-api-token",
        "BUGSINK_LOCALE": "en" 
      }
    }
  }
}

VS Code (with MCP Extension)

Configure in your .vscode/settings.json or User Settings:

"mcp.servers": {
  "bugsink": {
    "command": "npx",
    "args": ["@alvaroadlf/bugsink-mcp"],
    "env": {
      "BUGSINK_URL": "https://...",
      "BUGSINK_TOKEN": "...",
      "BUGSINK_LOCALE": "es"
    }
  }
}

🛠️ Available Tools

This server exposes a rich set of tools for the LLM.

🧠 Analysis Tools (The "Pro" Stuff)

analyze_issue_context

The most powerful tool. It fetches everything an LLM needs to understand a bug in one go:

1. Issue details (status, frequency, first/last seen).
2. The last 5 error events.
3. Full stacktraces for the latest event.

• Params: issue_id (UUID)

📊 Data Retrieval

list_projects

Lists all projects available to the user.

list_issues

Lists issues for a specific project.

• Params: project_id, status ('unresolved', 'resolved'), limit.

list_events (with Filtering)

Lists individual error occurrences. Now supports filtering!

• Params:
  • issue_id: The issue UUID.
  • limit: Max results.
  • browser: Filter by browser (e.g., "Safari").
  • os: Filter by OS (e.g., "Android").
  • error_message: Filter by text in the error message.

get_stacktrace

Get a pre-rendered, Markdown-formatted stacktrace for a specific event.

🏗️ Mutation (Management)

• create_project / update_project: Manage project settings and visibility.
• create_team / update_team: Manage teams.
• create_release: Manually register a release.

👨‍💻 Development

Architecture

This project uses a modular architecture:

• src/server.ts: Central MCP server logic.
• src/tools/: Discrete modules for Issues, Projects, Events, etc.
• src/i18n/: Localization logic.

Running Tests

# Run unit tests
npm test

# Run Integration Tests (Interactive)
# PRO TIP: This script validates your connection and translations properly!

# 1. Set environment variables
export BUGSINK_URL="https://your-bugsink.com"
export BUGSINK_TOKEN="your-token"

# 2. Run the test script
./test-integration.sh -l en   # Test in English
./test-integration.sh -l es   # Test in Spanish

⚠️ Compatibility Notes

This server is designed exclusively for Bugsink, a self-hosted, privacy-first alternative to Sentry.

• Bugsink API: Uses /api/canonical/0/.
• Sentry: This server is NOT compatible with the standard Sentry API. For Sentry, please use sentry-mcp.

📜 License

MIT © 2026 Alvaro Araoz