Telebugs MCP Server

An MCP (Model Context Protocol) server that allows AI agents to retrieve error reports from Telebugs, a self-hosted Sentry alternative.

Architecture

┌─────────────────┐                           ┌─────────────────────────────────────┐
│  Local Machine  │                           │              Remote VPS             │
│                 │         HTTPS             │                                     │
│  Claude Desktop │ ◄───────────────────────► │  Bun MCP Server   ───►  Telebugs    │
│                 │      (SSE transport)      │     :3100              SQLite DB    │
└─────────────────┘                           └─────────────────────────────────────┘

Related MCP server: otel-mcp

Features

• REST API backend (incremental) - When TELEBUGS_API_BASE_URL is set, project and membership tools call the Telebugs REST API (added in Telebugs 1.16.0) instead of writing to SQLite directly. Tools without a REST equivalent keep using the database, and every REST-backed tool falls back to direct DB access when REST is not configured.

• Direct database access - Reads and writes to Telebugs SQLite database

• MCP OAuth authentication - Browser-based OAuth flow backed by Telebugs users

• API key authentication - Still accepts existing Telebugs user API keys as bearer tokens

• Access control - Users only see projects they're members of

• SSE transport - Allows remote Claude Desktop connections

• Structured output - Every tool declares an outputSchema and returns structuredContent; failures are signaled with isError so clients can tell errors from data

• Token efficient - Compact JSON, defaults to open errors only

• Single binary - Cross-compile to Linux, no runtime dependencies

Available Tools

list_error_groups

Returns total_count for pagination.

list_reports

Returns total_count for pagination.

search_errors

resolve_error_group / unresolve_error_group / unmute_error_group

These tools only require group_id (number).

mute_error_group

add_note

delete_note

create_project (admin only)

update_project (admin only)

delete_project / regenerate_project_token (admin only)

These tools only require project_id (number).

add_project_member / remove_project_member (admin only)

get_project_token / list_project_members

These tools only require project_id (number).

list_platforms

No parameters. Returns all available platform names.

Installation

cd telebugs-mcp
bun install

Build

# Build for current platform
bun run build

# Build for Linux (for VPS deployment)
bun run build:linux

Configuration

Telebugs REST API (incremental migration)

Telebugs 1.16.0 introduced a REST API (/api/telebugs/v1). This server is gradually moving off direct database access onto that API. Set TELEBUGS_API_BASE_URL to opt in:

TELEBUGS_API_BASE_URL=https://telebugs.example.com/api/telebugs/v1 bun run start

The user's own Telebugs API key (users.api_key, tlbgs_...) is forwarded as the REST Bearer token — for API-key sessions it's the token the client already sent; for OAuth sessions it's read from the user record. If a user has no API key, that user's REST-backed tools fall back to direct DB access.

REST-backed when TELEBUGS_API_BASE_URL is set (otherwise direct DB):

• list_projects, create_project, update_project, delete_project

• get_project_token, add_project_member, remove_project_member

Still direct DB (no REST equivalent yet, or REST would change behavior):

• list_project_members — the REST endpoint requires admin; we allow any project member to list, so this stays on DB to avoid regressing non-admins.

• regenerate_project_token — no REST endpoint.

• All error-group, report, search, note, statistics, release, and sourcemap tools — to be migrated as the REST API gains group/report addressing by ID, notes, and statistics endpoints.

Running Locally

TELEBUGS_DB_PATH=/path/to/telebugs/storage/db/development.sqlite3 bun run dev

Deployment

Single Binary

# Copy to server
scp telebugs-mcp-linux root@your-server:~/telebugs-mcp-linux

# On server
chmod +x ~/telebugs-mcp-linux
./telebugs-mcp-linux

systemd Service

Copy telebugs-mcp.service to /etc/systemd/system/:

cp telebugs-mcp.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable telebugs-mcp
systemctl start telebugs-mcp

Check status:

systemctl status telebugs-mcp

Nginx Reverse Proxy (Optional)

location /mcp {
    proxy_pass http://127.0.0.1:3100;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # SSE support
    proxy_set_header Connection '';
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding off;
}

Claude Desktop Configuration

For OAuth-capable MCP clients, configure the server URL only. The client will discover OAuth metadata, open a browser sign-in page, and retry with the issued bearer token:

{
  "mcpServers": {
    "telebugs": {
      "url": "https://your-server/mcp"
    }
  }
}

When the MCP server runs behind a reverse proxy, set MCP_BASE_URL to the public HTTPS origin:

MCP_BASE_URL=https://your-server bun run start

The OAuth sign-in page is rendered by React with CSS generated from Tailwind by Bun's Tailwind plugin. It matches the Telebugs sign-in page, shows the requesting client and redirect origin, and requires explicit approval before issuing an authorization code. It accepts your Telebugs email/password, verified against the same bcrypt users.password_digest used by Telebugs. It can also accept a Telebugs sign-in link from /session/transfers/... when TELEBUGS_SECRET_KEY_BASE is set so the MCP server can derive Rails' active_record/signed_id verifier key and validate the signed id payload.

If Telebugs is configured with RAILS_MASTER_KEY instead of SECRET_KEY_BASE, read the value from the Telebugs app with bin/rails runner 'puts Rails.application.secret_key_base' and pass it to this server as TELEBUGS_SECRET_KEY_BASE.

For clients that do not support MCP OAuth yet, a static bearer token still works. Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "telebugs": {
      "url": "http://your-server:3100/mcp",
      "headers": {
        "Authorization": "Bearer your_telebugs_api_key"
      }
    }
  }
}

Getting Your API Key

1. Log into your Telebugs instance

2. Go to User → Account Settings → Security

3. Copy your API key

Security

• Admin-only operations enforced for project management (create, update, delete, token regen, membership)

• Write operations limited to error status changes, notes, and project management

• All mutations scoped to user's project memberships

• API keys validated against active users only

• OAuth access tokens are short-lived; OAuth clients and token hashes are persisted for re-authentication and refresh

• All queries filtered by user's project memberships

• Parameterized queries (no SQL injection)

Health Check

curl http://localhost:3100/health
# {"status":"ok"}

License

MIT