bugsink-mcp

A full read/write MCP server for Bugsink (self-hosted, Sentry-protocol-compatible error tracking), built directly against Bugsink's /api/canonical/0/ OpenAPI schema.

It exists because the existing bugsink-mcp package on npm only wraps the read side of the API (list/get). This one covers the full canonical API surface: resolving, muting, reopening and deleting issues, commenting, and creating/updating teams, projects and releases — plus a couple of correctness fixes over the original (see Fixes over the original).

Setup

Requires Node.js 18.17+.

1. In Bugsink, go to Account Settings → Auth Tokens and create a token.
2. Add the server to your MCP client.

Claude Code

One-liner, using the claude mcp CLI:

claude mcp add bugsink \
  -e BUGSINK_URL=https://bugs.example.com \
  -e BUGSINK_TOKEN=<your token> \
  -- npx -y github:fers4t/bugsink-mcp

This writes the equivalent of the following into ~/.claude.json (or pass --scope project to write a shared .mcp.json instead of the user-local config):

{
  "mcpServers": {
    "bugsink": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:fers4t/bugsink-mcp"],
      "env": {
        "BUGSINK_URL": "https://bugs.example.com",
        "BUGSINK_TOKEN": "<your token>"
      }
    }
  }
}

Restart Claude Code (or start a new session) afterwards — MCP tool lists are loaded at session start and won't pick up a config change mid-conversation.

Other MCP clients

Any client that reads a mcpServers map (Cursor, Windsurf, etc.) can use the same JSON shape shown above — point it at command: npx, args: ["-y", "github:fers4t/bugsink-mcp"], and the two required env vars.

npx installs straight from GitHub (no npm publish involved) and runs the prepare script to compile TypeScript on first use, then reuses its local cache on subsequent launches.

Environment variables

Variable	Required	Description
BUGSINK_URL	yes	Base URL of your Bugsink instance, e.g. https://bugs.example.com
BUGSINK_TOKEN	yes	Personal API token (Bearer auth)
BUGSINK_TIMEOUT_MS	no	Per-request timeout in ms (default 15000, clamped to 1000–120000)

See .env.example. Never commit a real token — the server reads it from the environment only.

Tools

Connectivity

Tool	Description
test_connection	Verify the URL/token work and report how many teams are visible

Teams

Tool	Description
list_teams	List all teams
get_team	Get a team by UUID
create_team	Create a team
update_team	Rename a team or change its visibility

Projects

Tool	Description
list_projects	List projects, optionally filtered by team
get_project	Get a project (including its DSN), optionally expanding the team
create_project	Create a project under a team
update_project	Update name/visibility/alert flags/retention/team

Issues

Tool	Description
list_issues	List issues for a project (sort by digest_order, digested_event_count or last_seen)
get_issue	Get an issue by UUID or friendly ID (e.g. PROJ-123)
delete_issue	Irreversibly delete an issue and its events
resolve_issue	Resolve now
resolve_issue_in_next_release	Resolve, regressing if a later release reports it again
resolve_issue_in_latest_release	Resolve as of the current latest release
reopen_issue	Reopen a resolved issue
mute_issue	Mute indefinitely
mute_issue_for	Mute for N periods (e.g. 3 days)
mute_issue_until	Mute until an event-count threshold is crossed in a period
unmute_issue	Unmute
add_issue_comment	Add a comment to an issue

Events

Tool	Description
list_events	List events (occurrences) for an issue
get_event	Get full event detail, including tags/contexts/raw payload
get_stacktrace	Render a rendered-Markdown stacktrace for an event

Releases

Tool	Description
list_releases	List releases for a project
get_release	Get a release by UUID
create_release	Create a release (needed for resolve_issue_in_next_release to regress correctly)

Fixes over the original

• get_stacktrace actually works. Bugsink's stacktrace endpoint returns text/markdown, not JSON. The original package called res.json() unconditionally and threw Unexpected token '#', "# TypeError"... is not valid JSON on every call. This server reads that endpoint as text.
• Write support: resolve/mute/reopen/delete/comment on issues, and create/update for teams, projects and releases — none of which the read-only original exposed.
• Bounded timeouts (AbortSignal.timeout, default 15s) on every request, so a hung upstream can't hang the MCP process indefinitely.
• Safe retries: idempotent GET requests get a bounded exponential-backoff-with-jitter retry on 502/503/504 or network failure. Mutating requests (POST/PATCH/DELETE) are never auto-retried, since retrying a write whose response was merely lost could duplicate side effects (e.g. a second identical comment).
• Input validation via Zod on every tool argument (numeric IDs, UUIDs, enums), so malformed input is rejected locally with a clear message instead of reaching the API.
• No secrets in output. Errors report the HTTP status and a truncated response body; the Authorization header value is never included in any log or thrown error.

Security notes

• This is a local stdio process — it does not open a network listener. Access control is whatever your MCP client already provides plus possession of BUGSINK_TOKEN.
• All diagnostics go to stderr; stdout is reserved for the JSON-RPC protocol stream.
• BUGSINK_URL must be http: or https:; plain HTTP to a non-local host prints a warning (your token would be sent unencrypted) but is not blocked, to support internal networks.
• Treat BUGSINK_TOKEN like any other credential: keep it out of version control, rotate it in Bugsink if it ever leaks, and scope it to the least-privileged user your workflow allows.

Development

npm install     # installs deps and runs the TypeScript build (prepare script)
npm run typecheck
npm run build   # compile src/ -> dist/
npm run dev     # watch mode

License

MIT