Telebugs MCP 서버

AI 에이전트가 자체 호스팅된 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에서 사용하는 것과 동일한 bcrypt users.password_digest에 대해 검증된 Telebugs 이메일/비밀번호를 허용합니다. 또한 TELEBUGS_SECRET_KEY_BASE가 설정되어 있으면 MCP 서버가 Rails의 active_record/signed_id 검증기 키를 도출하고 서명된 ID 페이로드를 검증할 수 있으므로 /session/transfers/...의 Telebugs 로그인 링크도 허용할 수 있습니다.

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