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