ai-task-board-mcp 0.3.0

MCP server exposing the AI Task Board to any MCP-capable AI agent

AI Task Board — MCP Server

Exposes the board to any MCP-capable AI agent (Claude Code/Desktop, Cursor, Cline, Windsurf, or a custom client — MCP is model-agnostic) as 8 typed tools mapped 1:1 onto the Board REST API. It is a thin client: it holds one scoped API key (one actor) and forwards calls. See the tool contract in docs/api/mcp-tools.md and per-client wiring + behavioral rules in docs/INTEGRATION.md.

Tools

list_projects · get_board · list_tasks · get_task (read) · claim_task · create_task · update_task (write) · add_report (report)

Conflict handling baked in:

• claim_task on a contested task returns who holds it and for how long (never steals it).
• update_task on a stale expected_version returns a version_conflict with advice to re-read and retry (never overwrites a human's edit).

Install & run

Published on PyPI — no clone needed:

uvx ai-task-board-mcp        # or: pip install ai-task-board-mcp && ai-task-board-mcp

Config via env: ATB_API_BASE_URL, ATB_API_KEY (= an actor), ATB_PROJECT_ID (optional — the agent calls list_projects).

For local development from source: uv venv .venv && uv pip install --python .venv -e ".[dev]", then .venv/bin/python -m atb_mcp.server.

Connect to an agent

Any MCP client uses the same command + args + env (see docs/INTEGRATION.md for Claude Desktop, Cursor, Windsurf, Cline, and custom clients). Claude Code example:

claude mcp add ai-task-board \
  --env ATB_API_BASE_URL=https://board.filbert.games \
  --env ATB_API_KEY=<your agent key> \
  -- uvx ai-task-board-mcp

Or add to a .mcp.json / claude_desktop_config.json:

{
  "mcpServers": {
    "ai-task-board": {
      "command": "uvx",
      "args": ["ai-task-board-mcp"],
      "env": {
        "ATB_API_BASE_URL": "https://board.filbert.games",
        "ATB_API_KEY": "<your agent key>"
      }
    }
  }
}

Pair it with the behavioral skill in ../skill/ so the agent knows how to run the board (claim before working, one report per step, respect priorities and other actors' claims).

Config (env)

Var	Default	Meaning
ATB_API_BASE_URL	http://127.0.0.1:8077	backend base URL
ATB_API_KEY	—	scoped key = the agent's actor identity
ATB_PROJECT_ID	—	default project when a tool omits project_id
ATB_TIMEOUT	15	HTTP timeout (s)

Tests

.venv/bin/python -m pytest

Spins up the real backend (via backend/.venv) as a subprocess and exercises all 8 tools end-to-end, including the claim-conflict and version-conflict paths.

Verify end-to-end (manual script)

With a seeded backend already running:

ATB_API_BASE_URL=http://127.0.0.1:8077 PYTHONPATH=. \
  .venv/bin/python scripts/verify_mcp.py