How do I use Telebugs MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Telebugs MCP Server Show me the latest open error groups" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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 │ └─────────────────┘ └─────────────────────────────────────┘

Features

Direct database access - Reads from Telebugs SQLite database (read-only)
API key authentication - Uses existing Telebugs user API keys
Access control - Users only see projects they're members of
SSE transport - Allows remote Claude Desktop connections
Token efficient - Compact JSON, defaults to open errors only
Single binary - Cross-compile to Linux, no runtime dependencies

Available Tools

Tool	Description
`list_projects`	List all accessible projects
`list_error_groups`	List deduplicated error groups with filtering
`get_error_group`	Get details of a specific error group
`list_reports`	List individual error occurrences
`get_report`	Get full report with backtrace, breadcrumbs, context
`get_statistics`	Get aggregated error statistics
`search_errors`	Full-text search across errors

list_error_groups

Parameter	Type	Default	Description
`project_id`	number	-	Filter by project ID
`status`	string	`"open"`	`"open"`, `"resolved"`, `"muted"`, or `"all"`
`error_type`	string	-	Filter by exact error type
`error_message`	string	-	Filter by error message (substring match)
`from`	string	-	Start date (ISO 8601)
`to`	string	-	End date (ISO 8601)
`limit`	number	20	Max results (1-100)
`offset`	number	0	Skip N results for pagination

Returns total_count for pagination.

list_reports

Parameter	Type	Default	Description
`group_id`	number	-	Filter by error group ID
`project_id`	number	-	Filter by project ID
`from`	string	-	Start date (ISO 8601)
`to`	string	-	End date (ISO 8601)
`limit`	number	20	Max results (1-100)
`offset`	number	0	Skip N results for pagination

Returns total_count for pagination.

search_errors

Parameter	Type	Default	Description
`query`	string	required	Full-text search query
`project_id`	number	-	Filter by project ID
`limit`	number	20	Max results (1-100)

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

Variable	Description	Default
`TELEBUGS_DB_PATH`	Path to Telebugs SQLite database	`/var/lib/docker/volumes/telebugs-data/_data/db/production.sqlite3`
`PORT`	HTTP port to listen on	`3100`

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

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

Log into your Telebugs instance
Go to User → Account Settings → Security
Copy your API key

Or query directly:

sqlite3 /path/to/production.sqlite3 "SELECT api_key FROM users WHERE active = 1;"

Security

Database opened in read-only mode
API keys validated against active users only
All queries filtered by user's project memberships
Parameterized queries (no SQL injection)

Health Check

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

License

MIT

Telebugs MCP Server

Telebugs MCP Server

Architecture

Features

Available Tools

list_error_groups

list_reports

search_errors

Installation

Build

Configuration

Running Locally

Deployment

Single Binary

systemd Service

Nginx Reverse Proxy (Optional)

Claude Desktop Configuration

Getting Your API Key

Security

Health Check

License

Resources

New MCP Servers

Latest Blog Posts

MCP directory API