npm package: @gits-id/mcp-taiga
Description: MCP Server for Taiga Project Management integration with Claude Code
Author: hyanuar0
Latest version: 1.4.1

# GITS MCP Taiga Server

MCP Server to connect Claude Code with Taiga Project Management.

## Features

- Access **all projects** you have permission to
- List and get project details
- CRUD operations for Epics, User Stories, Tasks, Issues
- Create, Read, Update Wiki Pages (no delete for safety)
- **Sprint/Milestone Management** - Create, update, move stories, get burndown stats
- **Team Management** - List members, assign work, view workload
- **Enhanced Search & Filtering** - Search by text, filter by tags, status, assignee
- **Comments & Collaboration** - Add/list comments on stories, tasks, and issues
- **Attachments** - Upload/list/view file attachments
- **Tags & Labels** - Manage tags with bulk operations
- **Reports & Analytics** - Sprint reports, velocity tracking, completion rates, epic progress
- **Status Overview** - Counts by status/assignee/priority, project/sprint dashboards

**Total: 66 tools available** (v1.4.1)

## Setup

### 1. Build project

```bash
make build
```

### 2. Setup for testing (optional)

If you want to test locally, copy `.env.test.example`:

```bash
cp .env.test.example .env.test
```

Edit `.env.test`:

```env
# For Taiga Cloud
TAIGA_URL=https://api.taiga.io/api/v1

# For self-hosted
# TAIGA_URL=https://your-taiga.com/api/v1

TAIGA_USERNAME=your_username
TAIGA_PASSWORD=your_password
```

**Note:** `.env.test` is only for local testing (`make test`). For Claude Code, ENV is passed via `--env` flag.

### 3. Test connection (optional)

After setting up `.env.test`, run:

```bash
make test
# or
npm run test:manual
```

This comprehensive test will:
- Test connection to Taiga API
- Test authentication
- Test all 66 tools across 14 categories
- Follow realistic PM workflow (milestone → epic → stories → tasks → comments → tags → reports)
- Create test data with prefix `[TEST-AUTO]`
- Display detailed results and summary

**What gets tested:**
- ✅ Projects & Team (v1.0.0, v1.2.0)
- ✅ Milestones/Sprint Management (v1.2.0)
- ✅ Epics & User Stories (v1.0.0)
- ✅ Tasks (v1.0.0)
- ✅ Comments & Collaboration (v1.3.0)
- ✅ Tags & Labels (v1.3.0)
- ✅ Issues (v1.0.0)
- ✅ Wiki Pages (v1.1.0)
- ✅ Search & Filtering (v1.2.0)
- ✅ Reports & Analytics (v1.4.0)
- ✅ Status Overview (v1.4.0)

**Note:** Testing is optional. You can use it directly with Claude Code without local testing.

### 4. Run server

```bash
make run
```

## Integration with Claude Code

**Taiga Cloud:**
```bash
claude mcp add gits-taiga \
  --env TAIGA_URL=https://api.taiga.io/api/v1 \
  --env TAIGA_USERNAME=your_username \
  --env TAIGA_PASSWORD=your_password \
  -- node /path/to/gits-mcp-taiga/build/index.js
```

**Self-hosted Taiga:**
```bash
claude mcp add gits-taiga \
  --env TAIGA_URL=https://your-taiga.com/api/v1 \
  --env TAIGA_USERNAME=your_username \
  --env TAIGA_PASSWORD=your_password \
  -- node /path/to/gits-mcp-taiga/build/index.js
```

Verify:

```bash
claude mcp list
```

## Commands

| Command | Description |
|---------|-------------|
| `make build` | Install dependencies and build |
| `make run` | Run MCP server |
| `make test` | Test connection and CRUD operations |
| `make clean` | Remove build files |

## Available Tools & Usage Examples

**Total: 66 tools** across 14 categories

| Category | Tools | Capabilities | Example Usage |
|----------|-------|--------------|---------------|
| **Projects** | 2 | List all projects, get project details | "Show me all my Taiga projects"<br>"Get details for project mobile-app" |
| **Epics** | 4 | List, get, create, update epics | "Create a new epic named 'API Development'"<br>"List all epics in project backend-api" |
| **User Stories** | 4 | List, get, create, update stories | "List all user stories in project mobile-app"<br>"Create a story for authentication feature" |
| **Tasks** | 4 | List, get, create, update tasks | "Create a task for user story #123"<br>"Show me all tasks in sprint 15" |
| **Issues** | 4 | List, get, create, update issues | "Show me all issues in project frontend"<br>"Create a bug report for login failure" |
| **Wiki Pages** | 4 | List, get, create, update wiki | "List all wiki pages in documentation project"<br>"Create a wiki page with slug 'getting-started'" |
| **Milestones/Sprints** | 6 | List, get, create, update, stats, move stories | "Create a new sprint called 'Sprint 15' starting Feb 1"<br>"Get burndown statistics for milestone 42"<br>"Move user story #123 to sprint 15" |
| **Team & Members** | 5 | List members, get details, workload, assign | "Show me all team members in project backend-api"<br>"Get the workload for user ID 5"<br>"Assign user story #456 to user ID 7" |
| **Search & Filtering** | 4 | Search stories/tasks/issues, filter by tags | "Search for user stories containing 'authentication'"<br>"Find all tasks assigned to user ID 5"<br>"Show me all user stories tagged with 'urgent'" |
| **Comments** | 6 | List/add comments for stories, tasks, issues | "Add a comment 'Great progress!' to user story #123"<br>"List all comments on task #456"<br>"Add a comment mentioning @john to issue #789" |
| **Attachments** | 6 | List/upload/get attachments | "Upload screenshot.png as attachment to story #123"<br>"List all attachments for task #456"<br>"Get details about attachment #789" |
| **Tags & Labels** | 6 | List tags, add/remove, bulk operations | "List all tags in project mobile-app"<br>"Add tags 'backend' and 'urgent' to story #123"<br>"Add tag 'priority' to stories: 100, 101, 102" |
| **Reports & Analytics** | 6 | Sprint reports, velocity, completion, progress | "Generate a comprehensive report for Sprint 15"<br>"Calculate our team velocity over last 3 sprints"<br>"Get progress report for epic #10" |
| **Status Overview** | 5 | Count by status/assignee/priority, dashboards | "Count all user stories by status in this project"<br>"Show me task distribution by team member"<br>"Give me a complete project overview dashboard" |

**Note:** You can access all projects you have permission to, no need to configure specific projects.

## Troubleshooting

**Error: Cannot reach API**
- Check TAIGA_URL in `.env`
- Make sure you're connected to VPN (for internal self-hosted)

**Error: Authentication failed**
- Check TAIGA_USERNAME and TAIGA_PASSWORD in `.env.test`
- Try logging in via browser first to verify credentials
- For Taiga Cloud: https://taiga.io
- For self-hosted: https://your-taiga.com

**Error: Failed to load configuration (during local testing)**
- Make sure `.env.test` has been created from `.env.test.example`
- Check all required variables: TAIGA_URL, TAIGA_USERNAME, TAIGA_PASSWORD

**Error: Failed to load configuration (in Claude Code)**
- Make sure all `--env` flags are filled when running `claude mcp add`
- Verify with `claude mcp list` to check config

**Error: 400 Bad Request when creating**
- Check project settings in Taiga
- Make sure required plugins are enabled (Epics, Scrum, Issues)

## License

MIT - GITS.ID