Taiga MCP Server

taiga-api-client

🇬🇧 English version — you are here · 🇷🇺 Русская версия

A TypeScript client for the Taiga REST API. Zero runtime dependencies, dual ESM + CJS, runs on Node ≥18, Bun ≥1.0 and any environment with a global fetch.

• 🔐 Bearer authentication with automatic token refresh and deduplication of concurrent refreshes
• 📦 Fully typed: types for every resource, payload and parameter
• 🚫 Zero runtime dependencies
• 🔄 Async iterators for pagination
• ⚠️ Typed errors (TaigaApiError, TaigaAuthError, TaigaRateLimitError, TaigaNetworkError)
• 🚀 Dual ESM + CJS build with .d.ts / .d.cts type maps

Installation

npm install taiga-api-client

or

bun add taiga-api-client

or

pnpm add taiga-api-client

Quick start

import { TaigaClient } from "taiga-api-client";

// baseUrl is the only required option. const client = new TaigaClient({ baseUrl: "https://api.taiga.io" });

// Log in (the username field accepts both username and email). await client.auth.login({ username: "alice@example.com", password: "secret" });

// Fetch projects you are a member of. const me = await client.users.me(); const projects = await client.projects.list({ member: me.id });

// Create a user story. const story = await client.userStories.create({ project: projects[0].id, subject: "Add OAuth login", description: "Support GitHub OAuth in addition to password login", });

// Iterate over every issue in the project (auto-pagination). for await (const issue of client.issues.paginate({ project: projects[0].id })) { console.log(#${issue.ref} ${issue.subject}); }

🤖 MCP server: Taiga for AI agents

This repository also ships [taiga-api-mcp-server](mcp/README.md) — a Model Context Protocol server built on this client. Point an MCP client (Claude Code, Claude Desktop, Cursor, …) at your Taiga account and it can read what is assigned to you, move items between statuses, create user stories, tasks, issues and epics, assign people, estimate, comment and plan sprints — with your own permissions and nothing more.

Statuses, members and sprints are addressed by name; the server resolves them against the project's own catalogs, so an agent never has to guess a numeric ID.

It also answers "what did we do last week" in one call: taiga_activity walks the project timeline and returns, per card touched in the window, what actually happened to it — status moves, closures (including the ones entered days later), comments, sprint moves, attachments. Taiga's list endpoints have no date filters, so this is the only way to get a period of work. Whether a story is finished comes from its tasks (tasks_done of tasks_total) and whether it was closed from the project's own statuses — the dates and the closed flag are filled in by hand, and often not at all. Both are answered twice over, as of today and as of the end of the window, because a card moved to Done three days later is not last week's work.

claude mcp add taiga   --env TAIGA_URL=https://api.taiga.io   --env TAIGA_USERNAME=you@example.com   --env TAIGA_PASSWORD=...   -- npx -y taiga-api-mcp-server

📖 Setup, tool reference and examples: [mcp/README.md](mcp/README.md)

💡 Looking up catalog IDs? Use filters_data

Most write operations need numeric IDs of project-specific catalog values (status, type, severity, priority, assignee, …). Don't fetch each catalog separately — every resource exposes a filters_data method that returns all of them in one request, scoped to the project.

const data = await client.issues.filtersData({ project: 42 });

const inProgress = (data.statuses as Array<{ id: number; name: string }>) .find((s) => s.name === "In progress");

await client.issues.create({ project: 42, subject: "...", status: inProgress!.id });

📖 Read the full guide: [docs/filters-data.md](docs/filters-data.md) — caching, available endpoints per resource, when it is _not_ enough.

Creating the client

Minimum:

const client = new TaigaClient({ baseUrl: "https://api.taiga.io" });

baseUrl is the only required option. Everything else is optional.

Full example:

const client = new TaigaClient({

baseUrl: "https://api.taiga.io", // ← required

// Authentication — pick one (or none, if you will call client.auth.login later): token: "...", // a previously obtained bearer token (session restore) refreshToken: "...", // its paired refresh token applicationToken: "...", // a static Application token, used instead of bearer

// Behavior: autoRefresh: true, // auto-refresh the bearer token on 401 (default true) timeoutMs: 30000, // request timeout in ms (default 30000) userAgent: "my-app/1.0", acceptLanguage: "en", apiPrefix: "/api/v1", // change only for self-hosted with a non-default prefix fetch: customFetch, // dependency-injected fetch (proxies, mocks)

// Token persistence hook: onTokenChange: async (tokens) => { if (tokens) await db.saveTokens(tokens); else await db.clearTokens(); }, });

TaigaClientOptions

Authentication

Three modes are supported:

Automatic token refresh

With autoRefresh: true (the default), the client transparently intercepts 401 responses, calls POST /auth/refresh, and retries the original request once. Concurrent 401s are deduplicated — /auth/refresh is called exactly once even if 10 requests fail simultaneously. If the refresh itself fails, tokens are cleared and a TaigaAuthError is thrown.

Persisting tokens across process restarts

const client = new TaigaClient({

baseUrl: "https://api.taiga.io", token: await db.loadToken(), refreshToken: await db.loadRefreshToken(), onTokenChange: async (tokens) => { if (tokens) await db.saveTokens(tokens); else await db.clearTokens(); }, });

onTokenChange is invoked:

• after client.auth.login(...) — with the new token pair;
• after a successful auto-refresh — with the new pair;
• after client.auth.logout() — with null.

The returned Promise is awaited before the request is retried, so your persistence is guaranteed to complete before the next request goes out.

Resources and methods

Every resource extends BaseResource, which provides standard CRUD. Specific resources add their own methods on top.

BaseResource — common CRUD

client.auth — authentication