Skip to main content
Glama
taiga-delegate

taiga-delegate

taiga-delegate

Delegate your Taiga board to AI agents — without handing them the keys to everything.

taiga-delegate is an MCP server for Taiga (self-hosted or taiga.io cloud). It gives Claude Code, Claude Desktop, or any MCP client full project-management tools — epics, stories, tasks, issues, sprints, wiki, comments, search — and is built around making that delegation safe:

  • Scoped tokens — confine an agent or external collaborator to just the epics you hand over (one or several): the epics themselves, their linked stories, their bugs. Everything else is invisible and denied with an explanation, not an opaque error.

  • Attribution without accounts — scoped collaborators share one Taiga identity but every comment is signed **[name]** and everything they create is tagged by-<name>, so the board always shows who did what.

  • Usage metering — every tool call is logged per token to a durable JSONL file; an owner-only mcp_usage_stats tool reports calls, denials, and top tools per collaborator.

Why

A tracker connection is normally an all-or-nothing grant: whoever holds the credentials can do everything the account can. That's the right amount of trust for your own agent — and more than you want to extend to anyone else. taiga-delegate narrows the grant per session and keeps the board legible while agents work it:

  • Least access. Each session gets exactly the slice it needs: the full board with the owner token, one epic with a scoped token. Out-of-scope items are hidden from the tool listing, and out-of-scope calls are denied with an explanation the calling model can act on instead of retrying.

  • Legible history. Several agents and collaborators can share one Taiga identity without blurring together: comments are signed **[name]**, created items carry a by-<name> tag, and the usage log ties every call to its token.

  • Safe writes. Updates patch only the fields being changed, carrying the object version — so assignees, sprint placements, and concurrent human edits survive agent activity.

  • Economical transport. Results are serialized once, at the boundary, into compact JSON with empty fields stripped (~44% smaller) — tool output that an LLM re-reads on every turn is the most expensive payload there is.

All of it is enforced in the server, not by instructions to the client — which matters, because you don't control what a collaborator connects with.

Related MCP server: taiga-mcp

Quick start (stdio, local)

Examples throughout use Claude Code because that's what this was built with — but the server is client-agnostic MCP; any MCP-capable agent connects the same way (see Any MCP client).

Requires Python 3.11+.

pip install git+https://github.com/hemanthkandru/taiga-delegate

claude mcp add taiga \
  --env TAIGA_URL=https://taiga.example.com \
  --env TAIGA_USERNAME=my-agent-user \
  --env TAIGA_PASSWORD=... \
  -- taiga-delegate

That's it — Claude Code spawns the server per session and gets 34 Taiga tools.

taiga.io cloud works the same way with TAIGA_URL=https://api.taiga.io. If your taiga.io account uses GitHub/GitLab/Google sign-in, either set a password in Taiga (user settings → password) or use an auth token via TAIGA_TOKEN instead of username/password.

Tip: create a dedicated Taiga user for the agent (e.g. my-agent) and add it to the projects it should manage. Keeps the audit trail clean and your own account out of the loop.

Quick start (HTTP, server deployment)

For a shared server — your team or external collaborators connect from anywhere:

cp .env.example .env    # fill in Taiga credentials + MCP_AUTH_TOKEN
docker compose up -d --build

Then from any machine:

claude mcp add --transport http taiga https://your-host/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

The container serves the MCP streamable-HTTP protocol on port 8765 at /mcp. Put your reverse proxy (nginx, Caddy, Traefik) in front for TLS; every request must carry a valid bearer token or it is rejected with 401 before reaching the protocol layer.

Environment:

Variable

Meaning

TAIGA_URL

Taiga API base URL (https://taiga.example.com or https://api.taiga.io)

TAIGA_USERNAME / TAIGA_PASSWORD

agent account credentials

TAIGA_TOKEN

alternative to username/password

MCP_TRANSPORT

stdio (default) or http

MCP_PORT

HTTP port, default 8765

MCP_AUTH_TOKEN

full-access bearer token — required in HTTP mode

MCP_SCOPED_TOKENS

scoped collaborator tokens, see below

MCP_USAGE_LOG

usage JSONL path, default usage.jsonl (compose mounts a volume at /data)

Scoped tokens: delegate epics, not the board

Give an outside developer (or a second AI agent) access to exactly the epics you choose:

MCP_SCOPED_TOKENS="alex:3f8a...48-hex...:2:117;vendor:b41c...:3:99,104"
#                  label:token:project_id:epic_id[,epic_id...][;more]

A session authenticated with a scoped token can:

  • see only that project, those epics, their linked stories, and issues tagged epic-<id>

  • create stories (auto-linked to the epic) and bugs (auto-tagged) — a multi-epic token passes epic_id to say which epic a new item belongs to; a single-epic token never has to

  • update and comment on items inside the scope

Everything else — other epics, other projects, deletes, sprints, wiki, project admin — is hidden from tools/list and denied with a message that explains the boundary, so the calling model course-corrects instead of retrying blindly.

Collaborators set their own display name per session with an X-Collaborator-Name header:

claude mcp add --transport http taiga https://your-host/mcp \
  --header "Authorization: Bearer <scoped-token>" \
  --header "X-Collaborator-Name: Alex"

Comments then appear as **[Alex]** looks done, closing, and created items carry a by-alex tag — attribution without creating a Taiga account or managing roles. The token label (not the self-set name) is what appears in the usage log, so metering stays authoritative.

Generate tokens however you like, e.g. openssl rand -hex 24.

Any MCP client — or no client at all

Scoping, signing, tagging, and metering are all enforced server-side, so they hold no matter what the collaborator connects with. Claude Code is shown above; any other MCP-capable tool (Cursor, Windsurf, a custom Agent SDK app) uses its standard HTTP server config:

{
  "mcpServers": {
    "taiga": {
      "type": "http",
      "url": "https://your-host/mcp",
      "headers": {
        "Authorization": "Bearer <scoped-token>",
        "X-Collaborator-Name": "Alex"
      }
    }
  }
}

The endpoint is stateless JSON-RPC, so even a plain script works:

curl -s https://your-host/mcp \
  -H "Authorization: Bearer <scoped-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"taiga_list_user_stories","arguments":{}}}'

Either way, the server decides what the token can see and do: untrusted header values are decoded defensively (UTF-8 with replacement), the self-set display name is sanitized before it can reach board content (markup and non-printable characters stripped, length-capped), token comparison is constant-time, and malformed arguments come back as structured errors rather than taking anything down.

Usage metering

Every tool call is appended to a JSONL log ({"ts": ..., "label": "alex", "tool": "taiga_create_issue", "ok": true}). The owner token gets an extra tool:

mcp_usage_stats(days=7)
→ per label: total calls, denied/failed, first/last seen, top 10 tools

Scoped sessions can't see or call it.

Tools

34 tools across projects, epics, user stories, tasks, issues, sprints, wiki, comments, and search — list/get/create/update/delete plus taiga_resolve_ref (UI #ref → internal id), taiga_link_story_to_epic, and bulk story creation. Noteworthy behaviors, all learned the hard way against a live board:

  • Updates are minimal PATCHes with the object version — python-taiga's own update() does a full PUT that silently wipes the assignee and sprint of anything you touch.

  • A comment parameter on update tools posts the comment atomically with the change — one call instead of two, which halves tracking cost for agent workflows.

  • Expired-token recovery — Taiga sessions expire (typically daily); the executor re-authenticates and retries once, so long-running HTTP deployments don't need restarts.

  • Comments actually work on epics (the REST endpoint exists; most clients miss it).

  • Compact results — JSON with separators collapsed and empty fields stripped; False/0 are kept.

Agent workflow templates

templates/ has drop-in instruction files for Claude Code:

  • templates/CLAUDE-tracking.md — a policy block for your CLAUDE.md that makes the agent track its own work automatically: features become epics + stories (two status calls per story), bug fixes become issues with test-case checklists.

  • templates/commands/fix-issue.md, templates/commands/new-feature.md — slash commands forcing each workflow.

  • templates/collaborator-CLAUDE.md — give this to a scoped collaborator; their Claude then knows to work only inside the delegated epic.

The templates target Claude Code's CLAUDE.md and slash-command formats, but they're plain markdown instructions — adapt them to your agent's equivalent (Cursor rules, AGENTS.md, a system prompt) and the server behaves identically. Scoping and attribution don't depend on the agent following them; they're enforced server-side either way.

Architecture

src/taiga_delegate/
├── config.py          # every env var parsed exactly once, validated at startup
├── scope/             # domain: Scope model + pure policy (no I/O, fully unit-testable)
├── usage/             # durable JSONL usage log + aggregation
├── taiga/
│   ├── client.py      # Taiga session, expiry recovery, raw REST gaps (PATCH, epic links)
│   ├── serialization.py  # wire objects → compact JSON, at the boundary
│   └── tools/         # one module per domain; registry pattern — adding a tool edits no dispatcher
└── server/            # MCP wiring: auth middleware, handlers, stdio/http entrypoints

Dependencies point inward: scope/ knows nothing about Taiga or MCP; the policy checks ownership through an injected BoardInspector protocol. Tests run without a Taiga server.

Development

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest
.venv/bin/ruff check src tests

License

MIT

Available Tools

35 tools
mcp_usage_statsA

Per-token MCP usage stats: total calls, denials, top tools, first/last seen for each token label. Owner (full token) only.

Inputs: days.

taiga_add_commentC

Add a comment to a userstory, task, issue, or epic.

Inputs: comment (required), object_id (required), object_type (required).

taiga_add_project_memberA

Invite a user to a project by email with a role (e.g. 'Product Owner', 'Back'). Existing Taiga users are added; unknown emails get an invitation.

Inputs: email (required), project_id (required), role_name.

taiga_bulk_create_storiesA

Create multiple user stories. Each needs 'subject', optionally 'description', 'tags'. IMPORTANT: epic_id must be the internal numeric ID (not ref #) — call taiga_list_epics first to get it.

Inputs: stories (required), project_id (required), epic_id, sprint_id.

taiga_create_epicB

Create an epic to group related user stories under a high-level goal.

Inputs: subject (required), project_id (required), tags, color, +2 more.

taiga_create_issueC

Create an issue with type, priority, severity.

Inputs: subject (required), project_id (required), tags, priority, +4 more.

taiga_create_projectB

Create a new Taiga project (owned by the connected account). Returns id and slug.

Inputs: name (required), is_private, description.

taiga_create_sprintC

Create a new sprint. Dates in YYYY-MM-DD format.

Inputs: name (required), end_date (required), project_id (required), start_date (required).

taiga_create_taskC

Create a task, optionally linked to a user story or sprint.

Inputs: subject (required), project_id (required), sprint_id, assigned_to, +2 more.

taiga_create_user_storyA

Create a user story with subject, description (acceptance criteria), tags, sprint, assignee, and optional epic. IMPORTANT: epic_id must be the internal numeric ID, NOT the ref # shown in the UI — call taiga_list_epics or taiga_resolve_ref first to get the internal ID.

Inputs: subject (required), project_id (required), tags, epic_id, +3 more.

taiga_create_wiki_pageC

Create a new wiki page. Slug should be lowercase with hyphens (e.g. 'sprint-retrospective').

Inputs: slug (required), content (required), project_id (required).

taiga_delete_epicA

Permanently delete an epic (its stories survive, unlinked). Irreversible.

Inputs: epic_id (required).

taiga_delete_issueB

Permanently delete an issue. Irreversible.

Inputs: issue_id (required).

taiga_delete_user_storyA

Permanently delete a user story. Irreversible — confirm with the user before bulk deletions.

Inputs: story_id (required).

taiga_delete_wiki_pageC

Permanently delete a wiki page by slug. Irreversible.

Inputs: slug (required), project_id (required).

taiga_get_epicB

Get full epic details including description and linked user stories.

Inputs: epic_id (required).

taiga_get_issueA

Get full issue details including description AND comments. taiga_list_issues returns only subject/status/assignee, so this is the only way to read what an issue actually says. Takes the internal id — use taiga_resolve_ref to convert a # ref first.

Inputs: issue_id (required).

taiga_get_projectB

Get project details: members, statuses, roles, priorities, issue types.

Inputs: project_id (required).

taiga_get_sprintC

Get sprint details with all stories in the sprint.

Inputs: sprint_id (required).

taiga_get_user_storyB

Get full story details including description, tasks, and comments.

Inputs: story_id (required).

taiga_get_wiki_pageC

Get the full content of a wiki page by its slug.

Inputs: slug (required), project_id (required).

taiga_link_story_to_epicA

Link an existing user story to an epic. Both epic_id and story_id must be internal IDs (not ref #s). Use taiga_resolve_ref to convert ref numbers first.

Inputs: epic_id (required), story_id (required).

taiga_list_epicsB

List all epics in a project with their status, assignee, and story count.

Inputs: project_id (required), status, assigned_to.

taiga_list_issuesA

List all issues in a project. Returns summary fields only — use taiga_get_issue for the description and comments.

Inputs: project_id (required).

taiga_list_projectsA

List all accessible Taiga projects with ID, name, slug.

Inputs: no named parameters.

taiga_list_sprintsC

List all sprints/milestones for a project.

Inputs: project_id (required).

taiga_list_user_storiesB

List user stories. Filter by status, sprint_id, epic_id, or assigned_to username.

Inputs: project_id (required), status, epic_id, sprint_id, +1 more.

taiga_list_wiki_pagesC

List all wiki pages in a project (slug and title).

Inputs: project_id (required).

taiga_resolve_refA

Convert a display reference number (e.g. #12 shown in the UI) to the internal ID. ALWAYS use this before commenting on or updating a story/task/issue by its # number.

Inputs: ref (required), project_id (required), object_type (required).

taiga_unlink_story_from_epicC

Remove a user story from an epic.

Inputs: epic_id (required), story_id (required).

taiga_update_epicB

Update epic fields: subject, description, status (by name), assigned_to, tags, color. Pass 'comment' to post a comment in the same call.

Inputs: epic_id (required), tags, color, status, +4 more.

taiga_update_issueA

Update an issue: subject, description, status (e.g. 'Closed' to resolve), priority, severity, assignee, tags. Pass 'comment' to post a comment in the same call.

Inputs: issue_id (required), tags, status, comment, +5 more.

taiga_update_user_storyC

Update story fields: subject, description, status (by name), sprint_id, assigned_to, tags. Pass 'comment' to post a comment in the same call.

Inputs: story_id (required), tags, status, comment, +4 more.

taiga_update_wiki_pageB

Update the content of an existing wiki page by slug. Creates it if it doesn't exist.

Inputs: slug (required), content (required), project_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 35 tools

    Disambiguation4/5

    Most tools are cleanly separated by resource and CRUD verb. Minor overlap exists between taiga_create_user_story and taiga_bulk_create_stories, and between taiga_add_comment and update tools that accept inline comments, but boundaries remain understandable. mcp_usage_stats is unrelated to the Taiga domain and slightly muddies the set.

    Naming Consistency4/5

    Nearly all tools follow a predictable taiga_verb_noun convention with snake_case. The lone mcp_usage_stats tool breaks both the prefix and domain pattern. Aside from that outlier, naming is highly consistent.

    Tool Count2/5

    At 35 tools, the surface is heavy for a project-management server and exceeds the rubric's 25+ threshold. While Taiga has many resources, the count feels inflated by partial CRUD sets and utility tools rather than a tightly scoped surface.

    Completeness2/5

    Coverage is strong for stories, issues, epics, and wiki pages, including delete operations. However, tasks only support create with no list/get/update/delete, sprints lack update/delete, projects lack update/delete, and membership/comments only support add. These gaps will block common agent workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Full-featured MCP server for Taiga project management, enabling AI agents to manage projects, epics, user stories, tasks, issues, sprints, wiki pages, memberships, and roles via Taiga API v1.
      100
      6
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for the Taiga project management API. Enables AI assistants to manage projects, issues, user stories, tasks, epics, sprints, and wiki pages via natural language commands.
      55
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that lets AI agents connect to LTD project workspaces to inspect project health, search and manage tasks, assign owners, and add comments, with scoped tokens and preview-confirm safety for writes.
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for Taiga project management, enabling LLM clients to inspect and manage projects, work items, sprints, comments, attachments, and wiki pages via 6 op-dispatching tools.
      6
      15 npm
      3
      MIT