@sixtynine-digital/blitz-mcp

MCP server for Blitz, the Sixtynine work tracker. It gives an assistant read and write access to projects, work items, comments, modules and cycles through the Blitz external API (/api/v1).

For installation and credentials see MCP_Setup.md in the repo root.

Configuration

| Variable | Required | Meaning | | ---------------------- | ----------- | ------------------------------------------------------------- | | BLITZ_API_URL | yes | Blitz instance URL, e.g. https://api-tasks.sixtynine.dev | | BLITZ_API_KEY | yes (stdio) | Personal access token, plane_api_<hex> | | BLITZ_WORKSPACE_SLUG | yes (stdio) | Workspace slug, e.g. sixtynine | | BLITZ_PROJECT_ID | no | Default project, so project_id can be omitted on every tool | | BLITZ_MCP_MODE | no | stdio (default) or http | | BLITZ_MCP_PORT | no | HTTP mode port, default 3100 |

In HTTP mode the credentials come from the query string per session (/mcp?api_key=...&workspace=...&project_id=...), so only BLITZ_API_URL is needed at startup.

Tools

Projects and metadata

| Tool | What it does | | --------------- | ------------------------------------------------------------------ | | list-projects | Projects in the workspace | | list-members | Members of a project, or of the workspace when no project is given | | list-states | Workflow states of a project, for state_id | | list-labels | Labels of a project | | create-label | Create a label |

Work items

| Tool | What it does | | ------------------------- | ------------------------------------------------------------------------------- | | list-work-items | Work items with filters, pagination and sorting; everything but the description | | list-work-items-summary | Same filters, minimal fields — use for overviews and large projects | | get-work-item | Look up by human identifier, e.g. BLITZ-20 | | get-work-item-by-id | Look up by UUID | | create-work-item | Create, optionally with modules and a cycle | | update-work-item | Update; only the fields you pass are changed | | delete-work-item | Delete permanently | | search-work-items | Full-text search across the workspace |

Both list tools accept state_group, state_id, module_id, cycle_id and parent_id (which narrows to the sub-items of a work item).

Reads carry cycle_id and module_ids as raw UUIDs, plus cycle and modules with the names resolved. The UUID fields are the ones to hand back to a write tool.

Modules and cycles

| Tool | What it does | | ----------------------- | ----------------------------------------------------------------- | | list-modules | Modules of a project; archived ones are left out | | set-work-item-modules | Add, remove or replace the modules a work item belongs to | | list-cycles | Cycles of a project | | set-work-item-cycle | Put a work item into a cycle, move it, or take it out with null |

A work item can belong to several modules but at most one cycle, which is why the two tools have different shapes.

set-work-item-modules takes add and/or remove, or replace — not both. Prefer add/remove: they are idempotent and unaffected by concurrent edits. replace reads the current membership first, so a simultaneous edit elsewhere can be lost.

Membership is not part of the work item write endpoint, so create-work-item and update-work-item apply it in follow-up requests. That makes those calls non-atomic; the response reports each part separately so a partial failure is visible.

Comments

| Tool | What it does | | ----------------- | ---------------------------------- | | list-comments | Comments on a work item | | add-comment | Add a comment (HTML) | | update-comment | Edit a comment; marks it as edited | | delete-comment | Delete a comment | | list-activities | Change history of a work item |

Editing and deleting are limited to the author of the comment and project admins. Anything else comes back as 403.

Links

| Tool | What it does | | ----------------------- | ----------------------------------------------------------------- | | list-work-item-links | External links on a work item | | add-work-item-link | Attach a URL, e.g. the pull request that implements the work item | | delete-work-item-link | Remove a link |

Resources

| URI | Contents | | -------------------------------------- | ---------------------------- | | blitz://projects | Projects in the workspace | | blitz://projects/{project_id}/states | Workflow states of a project | | blitz://projects/{project_id}/labels | Labels of a project |

Development

pnpm --filter @sixtynine-digital/blitz-mcp check:types
pnpm --filter @sixtynine-digital/blitz-mcp check:lint
pnpm --filter @sixtynine-digital/blitz-mcp test
pnpm --filter @sixtynine-digital/blitz-mcp build

The version the server reports is injected at build time from package.json, so bumping version there is enough.

Releasing

The published package is what the deployed HTTP server runs: Dockerfile.mcp installs it from npm rather than building the local source. Order matters.

1. Merge and deploy the backend first when the release depends on an API change.
2. pnpm --filter @sixtynine-digital/blitz-mcp build && npm publish
3. Bump the pin in Dockerfile.mcp to the version just published, and commit. The pin is what busts the Docker layer cache — without it a rebuild can reinstall the old version.
4. Redeploy the mcp service.

To roll back, pin the previous version and redeploy.