Telebugs MCP サーバー

セルフホスト型の Sentry 代替ツールである Telebugs からエラーレポートを取得できるようにする MCP (Model Context Protocol) サーバーです。

アーキテクチャ

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

Related MCP server: otel-mcp

機能

• 直接データベースアクセス - Telebugs の SQLite データベースの読み書き

• MCP OAuth 認証 - Telebugs ユーザーによるブラウザベースの OAuth フロー

• API キー認証 - 既存の Telebugs ユーザー API キーをベアラートークンとして利用可能

• アクセス制御 - ユーザーがメンバーであるプロジェクトのみを表示

• SSE トランスポート - リモートの Claude Desktop 接続をサポート

• トークン効率化 - コンパクトな JSON、デフォルトで未解決エラーのみを対象

• シングルバイナリ - Linux 向けクロスコンパイル、ランタイム依存関係なし

利用可能なツール

list_error_groups

ページネーション用に total_count を返します。

list_reports

ページネーション用に total_count を返します。

search_errors

resolve_error_group / unresolve_error_group / unmute_error_group

これらのツールは group_id (number) のみが必要です。

mute_error_group

add_note

delete_note

create_project (管理者のみ)

update_project (管理者のみ)

delete_project / regenerate_project_token (管理者のみ)

これらのツールは project_id (number) のみが必要です。

add_project_member / remove_project_member (管理者のみ)

get_project_token / list_project_members

これらのツールは project_id (number) のみが必要です。

list_platforms

パラメータなし。利用可能な全プラットフォーム名を返します。

インストール

cd telebugs-mcp
bun install

ビルド

# Build for current platform
bun run build

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

設定

ローカルでの実行

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

デプロイ

シングルバイナリ

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

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

systemd サービス

telebugs-mcp.service を /etc/systemd/system/ にコピーします:

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

ステータスの確認:

systemctl status telebugs-mcp

Nginx リバースプロキシ (オプション)

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 の設定

OAuth 対応の MCP クライアントの場合、サーバー URL のみを設定します。クライアントは OAuth メタデータを検出し、ブラウザのサインインページを開き、発行されたベアラートークンで再試行します:

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

MCP サーバーをリバースプロキシの背後で実行する場合は、MCP_BASE_URL を公開 HTTPS オリジンに設定してください:

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

OAuth サインインページは、Bun の Tailwind プラグインによって生成された CSS を使用して React でレンダリングされます。Telebugs のサインインページと一致し、リクエスト元のクライアントとリダイレクトオリジンを表示し、認可コードを発行する前に明示的な承認を求めます。Telebugs が使用する users.password_digest の bcrypt と照合される Telebugs のメールアドレス/パスワードを受け付けます。また、TELEBUGS_SECRET_KEY_BASE が設定されている場合、/session/transfers/... からの Telebugs サインインリンクも受け付けます。これにより、MCP サーバーは Rails の active_record/signed_id 検証キーを導出し、署名付き ID ペイロードを検証できます。

Telebugs が SECRET_KEY_BASE の代わりに RAILS_MASTER_KEY で設定されている場合は、Telebugs アプリで bin/rails runner 'puts Rails.application.secret_key_base' を実行して値を取得し、TELEBUGS_SECRET_KEY_BASE としてこのサーバーに渡してください。

MCP OAuth をまだサポートしていないクライアントの場合は、静的なベアラートークンが引き続き機能します。~/Library/Application Support/Claude/claude_desktop_config.json (macOS) に追加してください:

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

API キーの取得方法

1. Telebugs インスタンスにログイン

2. ユーザー → アカウント設定 → セキュリティ に移動

3. API キーをコピー

セキュリティ

• プロジェクト管理（作成、更新、削除、トークン再生成、メンバーシップ）には管理者のみの操作を強制

• 書き込み操作はエラー状態の変更、メモ、プロジェクト管理に限定

• すべての変更はユーザーのプロジェクトメンバーシップの範囲内に限定

• API キーはアクティブなユーザーに対してのみ検証

• OAuth アクセストークンは短命であり、MCP サーバーのメモリ内に保持

• すべてのクエリはユーザーのプロジェクトメンバーシップによってフィルタリング

• パラメータ化されたクエリ（SQL インジェクションなし）

ヘルスチェック

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

ライセンス

MIT