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

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

Related MCP server: Sierra Navigator Cloud

Tools

Connectivity

Teams

Projects

Issues

Events

Releases

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