Taiga MCP Server

Model Context Protocol (MCP) server for Taiga project management, written in TypeScript and built on the Model Context Protocol SDK over stdio transport. It connects LLM clients to Taiga instances to inspect and manage projects, work items (issues, user stories, tasks, epics), sprints, comments, attachments, and wiki pages.

The server consolidates all capabilities into 6 op-dispatching tools designed for minimal token overhead and dense, human- and LLM-readable text responses.

Requirements and Configuration

• Node.js >= 20.11

• A Taiga account on taiga.io or a self-hosted Taiga instance

• Three environment variables configured:

MCP Client Configuration

Add the server to your MCP client configuration (such as claude_desktop_config.json or your harness configuration).

Using Local Checkout

When running from a local checkout, run npm run build first to compile the TypeScript source into dist/.

{
  "mcpServers": {
    "taiga": {
      "command": "node",
      "args": ["/absolute/path/to/dist/src/index.js"],
      "env": {
        "TAIGA_API_URL": "https://api.taiga.io/api/v1",
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Using npx

The package is not yet published to npm, so the npx configuration below is forward-looking:

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_API_URL": "https://api.taiga.io/api/v1",
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Related MCP server: @illodev/taiga-mcp

Containers

The included two-stage Dockerfile uses Node 22 Alpine with a non-root node user. The build stage compiles the TypeScript source, and the runtime stage packages only the compiled dist/src output and production dependencies.

Build the container image:

docker build -t mcp-taiga .

Run the container attached to standard I/O:

docker run --rm -i --env-file .env mcp-taiga

Podman works by direct substitution: replace docker with podman in the commands above.

Point an MCP client configuration at the container runner:

{
  "mcpServers": {
    "taiga": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/absolute/path/to/.env", "mcp-taiga"]
    }
  }
}

There is deliberately no compose file. An MCP stdio server must be spawned attached directly to its client's stdin and stdout streams, and exits when that stdin stream closes. Process supervisors or compose setups that attempt to keep long-running background services alive cause infinite restart loops and container name conflicts.

Conventions

• Projects: Project arguments accept a numeric project ID (e.g. 19) or a slug (e.g. "acme-web").

• Work Items: Work items accept a numeric database ID (e.g. 1888) or a reference prefixed with hash (e.g. "#70"). A #reference requires the project argument to resolve.

• People: Member arguments accept a numeric user ID, username (e.g. "jdoe"), full name (e.g. "Jane Doe"), or the literal "me".

• Taxonomies: Statuses, priorities, severities, issue types, and sprint names accept human-readable names and are resolved to numeric IDs server-side.

• Multi-Assignee User Stories: Taiga user stories support multiple assignees via assigned_users. Filtering by assignee on work list type:story matches co-assignees, and listings display all assignees rather than only the primary.

• Dense Text Results: Results are plain text formatted with one dense line per record or clean key-value blocks for detail views. No consumer reads structuredContent, so results are text only. An empty collection is reported as <items> in <project>: 0 rather than an error.

• Full Collections: List endpoints return complete collections because the client sends the x-disable-pagination: true request header, eliminating multi-page roundtrips.

Why Six Tools

Single-purpose tool proliferation creates substantial context window overhead before any tool is invoked. Consolidating functionality into 6 op-dispatching domain tools keeps the tools/list payload to about 10,267 characters (~2,775 tokens).

Output schemas are deliberately absent from tool registrations: MCP client bridges concatenate text content and ignore outputSchema and structuredContent, so omitting output schemas eliminates unnecessary token overhead on session startup.

Tool Reference

The server exposes 6 tools covering 28 operation pairs.

1. projects

List or inspect Taiga projects and verify credentials.

2. work

Manage issues, user stories, tasks, and epics (type: issue, story, task, epic).

3. sprints

Manage sprints (milestones) and inspect progress statistics.

Sprint deletion is intentionally not exposed: removing a milestone detaches every story and task on it, making it a board-wide edit that belongs in the Taiga UI.

4. comments

List, add, edit, or delete comments on work items and wiki pages (type: issue, story, task, epic, wiki).

5. attachments

Manage file attachments on work items and wiki pages (type: issue, story, task, epic, wiki).

6. wiki

Manage wiki pages and page subscriptions within a project.

Reliability and Safety

• Rate Limiting (429): The server retries HTTP 429 responses at most twice, honoring the server Retry-After header. If the required wait exceeds the 5-second ceiling (MAX_THROTTLE_WAIT_MS), it throws immediately with a retry message instead of sleeping.

• 5xx Errors Never Retried: 5xx responses are never retried automatically because mutating requests (such as POST) may have already been applied on the server; repeating them risks creating duplicate records.

• Metadata Cache: Project metadata (slug lookups, user memberships, and taxonomy lists for statuses, priorities, severities, and issue types) is cached for 60 seconds (METADATA_TTL_MS) via getMetadata. Work items, comments, and attachments are never cached.

• Timeouts: HTTP requests enforce a 30-second timeout (REQUEST_TIMEOUT_MS).

• HTTPS Enforcement: The server emits a warning to stderr if TAIGA_API_URL uses unencrypted HTTP to a non-loopback host.

• Restricted Attachment Downloads: Attachment downloads are restricted strictly to the configured Taiga hostname with no redirects allowed (maxRedirects: 0), bounded to a maximum file size of 10 MB (MAX_ATTACHMENT_BYTES). The download request does not send the Taiga bearer token to media hosts.

• File Overwrite Protection: Attachment download with savePath refuses to overwrite an existing local file.

• Single-Target Deletions: Deletion operations accept exactly one target at a time. Batch operations are create-only (up to 20 items), preventing accidental board-wide deletions.

Development

File Layout

src/index.ts            # Server entrypoint, stdio transport, resource registration, tool registry
src/api.ts              # Authenticated axios transport, generic HTTP helpers (get, post, patch, del), token management, retry policy, metadata cache
src/taiga.ts            # Domain helpers: resolution (projects, items, members, taxonomies, sprints) and optimistic concurrency patch
src/types.ts            # Taiga payload interfaces, tool definitions, and type contracts
src/format.ts           # Dense pipe-separated single-line renderers and detail views
src/utils.ts            # MCP response builders (createSuccessResponse, createErrorResponse, guard) and formatting helpers
src/constants.ts        # Endpoints, limits (batch size, attachment size), status labels, error messages
src/tools/index.ts      # Tool registry aggregating all tools and registering with McpServer
src/tools/projects.ts   # projects tool (list, get, whoami)
src/tools/work.ts       # work tool (list, get, create, update, link, unlink, delete across issues, stories, tasks, epics)
src/tools/sprints.ts    # sprints tool (list, get, create, stats)
src/tools/comments.ts   # comments tool (list, add, edit, delete)
src/tools/attachments.ts # attachments tool (list, upload, download, delete)
src/tools/wiki.ts       # wiki tool (list, get, create, update, delete, watch)
test/unitTest.ts        # Offline unit tests for pure helpers, formatting functions, response builders, and tool invariants
test/protocolTest.ts    # Protocol tests verifying MCP stdio handshake, server capabilities, tool count, and tools/list budget
test/apiContractTest.ts # Contract tests driving every tool op against an in-process mock Taiga HTTP server, asserting outgoing HTTP requests
test/integration.ts     # Live integration smoke test against a real Taiga instance (read-only, skips without credentials)

NPM Scripts

• npm run build: Compiles TypeScript from src/ and test/ into dist/ via tsc.

• npm run check: Type-checks TypeScript code without emitting output (tsc --noEmit).

• npm run lint: Runs oxlint across src/ and test/.

• npm start: Runs the compiled server (node dist/src/index.js).

• npm test: Compiles and runs unit, protocol, and contract test suites in sequence.

• npm run test:unit: Compiles and runs offline unit tests.

• npm run test:protocol: Compiles and runs MCP protocol tests over stdio.

• npm run test:contract: Compiles and runs API contract tests against the mock Taiga server.

• npm run test:integration: Compiles and runs live integration tests against a live instance.

• npm run prepublishOnly: Runs type check, linting, and full test suite before publishing.

Test Suites

1. Unit Tests (test/unitTest.ts): Offline unit tests asserting pure formatting functions, response builders, identifier resolution helpers, and tool-definition invariants without network calls or credentials.

2. Protocol Tests (test/protocolTest.ts): Protocol tests asserting the real MCP stdio handshake, server version and capabilities, tool schemas, and the tools/list character budget against a spawned server process.

3. Contract Tests (test/apiContractTest.ts): Contract tests asserting that every tool and op sends the expected outgoing HTTP requests (method, endpoint, query parameters, headers, and payload) and processes responses against an in-process mock Taiga HTTP server.

4. Integration Tests (test/integration.ts): Live integration smoke tests asserting read-only tool operations against a real Taiga instance over stdio (skipped when credentials are not configured).