zube-mcp

MCP server for the Zube.io project management API. Exposes Zube boards, cards, epics, tickets, sprints, and workspaces as tools that AI assistants can call.

Setup

Prerequisites

• Python 3.10+

• uv:

  • macOS: brew install uv

  • Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" or winget install astral-sh.uv

  • Any platform: pip install uv

• SSH access to this GitHub repo

1. Get your Zube API credentials

1. Go to Zube.io → Account Settings → API Keys

2. Create a new API key — this gives you a Client ID and a private key file (PEM)

3. Save the private key somewhere safe (e.g. ~/.zube/private-key.pem)

2. Configure in Cursor

Add to your .cursor/mcp.json (project-level or global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "zube": {
      "command": "uvx",
      "args": ["--from", "git+ssh://git@github.com/reachreporting/zube-mcp", "zube-mcp"],
      "env": {
        "ZUBE_CLIENT_ID": "your-client-id-here",
        "ZUBE_PRIVATE_KEY_PATH": "/path/to/your/private-key.pem"
      }
    }
  }
}

Replace the env values with your own Zube credentials. uvx will install the package directly from GitHub — no clone needed.

To pin a specific version, tag a release and append it to the URL:

git+ssh://git@github.com/reachreporting/zube-mcp@v0.3.0

Alternative: local install

If you prefer to clone and run locally:

git clone git@github.com:reachreporting/zube-mcp.git
cd zube-mcp
pip install -e .

Then point the Cursor config at your local path:

"args": ["--from", "/path/to/zube-mcp", "zube-mcp"]

Related MCP server: Fizzy Do MCP

Development

Making changes

After editing the source code, you must bump the version in pyproject.toml for Cursor to pick up changes. This is because uvx caches the built package by version — if the version hasn't changed, it serves the stale cached copy.

# 1. Edit code in zube_mcp/
# 2. Bump version in pyproject.toml (e.g. 0.2.0 → 0.3.0)
# 3. Commit and push
# 4. In Cursor: Settings → MCP → toggle zube off, then on

To verify your changes locally before restarting Cursor:

uvx --from . python3 -c "
from zube_mcp.server import mcp
import inspect
from zube_mcp.server import list_cards
print(inspect.signature(list_cards))
"

Zube API reference

Full API docs: https://zube.io/docs/api

Key concepts for adding new filters:

• List endpoints support where[field]=value query params for filtering

• The _build_params() helper in server.py converts a where dict into these query params automatically

• Array filters (e.g. assignee_ids) use where[field][]=value (handled by _build_params when the value is a list)

• Card numbers (the #12345 visible in the UI) are distinct from internal card IDs — use where[number] to filter by the visible number

Known Zube API quirks

• get_card requires the internal card ID, not the visible card number. Use get_card_by_number to look up by the human-visible #number.

• search_key on list endpoints is a full-text search and can be unreliable for finding cards by number.

• List responses return items in data array with a pagination object.

• Rate limit: 1 request/second. Short bursts are tolerated but sustained higher rates will be rejected.

Available Tools

Person & Accounts

Projects

Workspaces (Kanban Boards)

Cards (Issues / PRs)

Card Comments

Epics

Sprints

Tickets

Labels & Members

Architecture

zube_mcp/
  auth.py      # RS256 JWT creation for Zube's refresh token flow
  client.py    # Async HTTP client with automatic token management
  server.py    # FastMCP tool definitions (40 tools)

The auth flow:

1. Sign a 60-second JWT with your private key

2. Exchange it at POST /api/users/tokens for a 24-hour access token

3. The client auto-refreshes when the token is near expiry