Taiga MCP Server

A production-ready Model Context Protocol (MCP) server for Taiga Project Management

Python 3.10+ License: MIT MCP

Getting Started • Features • Tools • Architecture • Contributing

📋 Overview

Taiga MCP Server enables seamless integration between Large Language Models (LLMs) and Taiga project management platform through the Model Context Protocol. Built with Python's async/await patterns and type-safe Pydantic models, it provides a robust, production-ready solution for AI-powered project management automation.

Why Taiga MCP?

🤖 Natural Language Interface: Interact with Taiga using conversational commands
🔄 Async-First: Built on modern async/await for high performance
🛡️ Type-Safe: Full Pydantic validation for reliability
🎯 Production Ready: Comprehensive error handling and logging
🔌 Extensible: Clean architecture for easy feature additions
📦 Zero Config: Works out-of-the-box with Claude Desktop, Cursor, Windsurf

✨ Features

Core Capabilities

Feature	Description
🔐 Authentication	Token-based auth with automatic refresh
📊 Project Management	List, view, and search projects by ID or slug
📝 User Stories	Full CRUD operations with pagination support
✅ Task Management	Create and organize tasks within stories
👥 Team Collaboration	View members and assign work
🏷️ Rich Metadata	Tags, story points, due dates, custom fields
🔍 Flexible Queries	Support for IDs, slugs, and reference numbers (#42)

Technical Features

Async Architecture: Non-blocking I/O for optimal performance
Smart Caching: Token management with auto-refresh
Intelligent Pagination: Auto-fetch all or page-by-page
Optimistic Locking: Version-based updates prevent conflicts
Role-Based Points: Automatic detection and handling
Flexible Identifiers: Use IDs, slugs, or #ref numbers interchangeably

🚀 Quick Start

Prerequisites

Python: 3.10 or higher
Taiga Account: taiga.io or self-hosted instance
MCP Client: Claude Desktop, Cursor, Windsurf, or any MCP-compatible client

Installation

# Clone the repository git clone https://github.com/yourusername/taiga-mcp.git cd taiga-mcp # Create virtual environment (or use conda) python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # Install with dev dependencies pip install -e ".[dev]" # Configure credentials cp .env.example .env nano .env # Add your Taiga credentials

Configuration

Create .env file:

TAIGA_API_URL=https://api.taiga.io/api/v1 TAIGA_USERNAME=your_username TAIGA_PASSWORD=your_password DEBUG=false

See

🛠️ Available Tools

The server exposes 10 tools through the MCP protocol:

Authentication

Tool

Description

Parameters

authenticate

Authenticate with Taiga API

username

(optional),

password

(optional)

Project Management

Tool	Description	Parameters
`listProjects`	List all accessible projects	None
`getProject`	Get project details	`projectIdentifier` (ID or slug)
`listProjectMembers`	List project team members	`projectIdentifier`

User Story Management

Tool	Description	Parameters
`createUserStory`	Create a new user story	`projectIdentifier` , `subject` , `description` , , `tags` *
`listUserStories`	List stories with pagination	`projectIdentifier` , `pageSize` , , `fetchAll` *
`getUserStory`	Get story details	`userStoryIdentifier` , `projectIdentifier` *
`updateUserStory`	Update existing story	`userStoryIdentifier` , `projectIdentifier` , , `description` , , `assignedTo` , , `points` ,

Task Management

Tool

Description

Parameters

createTask

Create task in story

projectIdentifier

userStoryIdentifier

subject

description

tags

listUserStoryTasks

List tasks for a story

userStoryIdentifier

projectIdentifier

* = optional parameter

💬 Example Usage

Once configured with your LLM client, use natural language:

"List all my Taiga projects" "Show me details about project 'mobile-app'" "Create a user story in backend-api titled 'Implement OAuth2 authentication' with description 'Add JWT-based OAuth2 flow for API endpoints'" "List all user stories in the mobile-app project" "Update user story #42 - set status to 'In Progress' and assign to john" "Show me all tasks for user story #42" "Create a task in story #42 titled 'Write unit tests for auth module'"

🏗️ Architecture

Tech Stack

Component	Technology	Purpose
Protocol	MCP 1.0	LLM-tool communication
Language	Python 3.10+	Core implementation
HTTP Client	httpx	Async Taiga API calls
Validation	Pydantic v2	Type-safe data models
Config	pydantic-settings	Environment management
Testing	pytest + pytest-asyncio	Test framework

Project Structure

taiga-mcp/ ├── app/ # Main application package │ ├── core/ # Core functionality │ │ ├── auth.py # Authentication & token management │ │ ├── client.py # Async HTTP client wrapper │ │ └── exceptions.py # Custom exception hierarchy │ ├── models/ # Pydantic data models │ │ ├── project.py # Project & member models │ │ ├── userstory.py # User story models │ │ ├── task.py # Task models │ │ ├── user.py # User models │ │ └── status.py # Status models │ ├── services/ # Business logic layer │ │ ├── project_service.py # Project operations │ │ ├── userstory_service.py # User story operations │ │ ├── task_service.py # Task operations │ │ └── user_service.py # User operations │ ├── config.py # Settings management │ └── server.py # MCP server & tool definitions ├── tests/ # Test suite │ ├── unit/ # Unit tests │ └── integration/ # Integration tests ├── pyproject.toml # Project metadata & dependencies ├── README.md # This file ├── RUN.md # Setup & usage guide └── .env.example # Example environment config

Design Patterns

1. Async/Await Throughout

All I/O operations use Python's async/await for non-blocking execution:

async with TaigaClient() as client: projects = await project_service.list_projects()

2. Service Layer Pattern

Business logic is encapsulated in service classes:

class ProjectService: async def list_projects(self) -> list[Project]: data = await self.client.get("/projects") return [Project(**proj) for proj in data]

3. Pydantic Validation

All data is validated using Pydantic models:

class UserStory(BaseModel): id: int subject: str tags: list[str] = Field(default_factory=list) @field_validator("tags", mode="before") @classmethod def normalize_tags(cls, v: Any) -> list[str]: # Handle both ['tag'] and [['tag', None]] formats ...

4. Error Handling

Custom exception hierarchy for precise error handling:

try: await client.get("/projects/123") except ResourceNotFoundError as e: logger.error(f"Project not found: {e.identifier}") except TaigaAPIError as e: logger.error(f"API error: {e.status_code}")

🔧 Development

Setup Development Environment

# Install with development dependencies pip install -e ".[dev]" # Run tests pytest # Run tests with coverage pytest --cov=app --cov-report=html # Format code black app/ tests/ # Lint code ruff check app/ tests/ # Type check mypy app/

Running Tests

# All tests pytest # Specific test file pytest tests/unit/test_auth.py -v # Integration tests (requires Taiga credentials) pytest tests/integration/ -v # With coverage report pytest --cov=app --cov-report=term-missing

Code Quality Tools

Tool	Purpose	Command
Black	Code formatting	`black app/ tests/`
Ruff	Fast linting	`ruff check app/ tests/`
Mypy	Type checking	`mypy app/`
Pytest	Testing	`pytest`

🗺️ Roadmap

Phase 1: Core Features ✅

Authentication & token management
Project listing and details
User story CRUD operations
Task management
Team member listing
Smart pagination
Flexible identifiers (ID/slug/#ref)

Phase 2: Enhanced Features 🚧

Caching layer (Redis/in-memory)
Rate limiting
Bulk operations
Epic support
Sprint/Milestone management
Issues/Bugs tracking
Wiki page integration
File attachments
Comments on stories/tasks
Custom field support
Activity history tracking

Phase 3: Advanced Features 🎯

Standalone CLI tool
Analytics & reporting
Data export/import
Webhook support
Notification integrations (Slack, Email)
Project templates
Burndown charts
Time tracking

🤝 Contributing

Contributions are welcome! Here's how to get started:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Add tests: Ensure coverage for new code
Run quality checks:
black app/ tests/ ruff check app/ tests/ mypy app/ pytest
Commit your changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Follow existing code style (Black formatting)
Add type hints to all functions
Write docstrings for public APIs
Include tests for new features
Update documentation as needed

📝 License

This project is licensed under the The GNU General Public License v3.0 - see the LICENSE file for details.

🙏 Acknowledgments

Model Context Protocol - For the excellent LLM-tool integration standard
Taiga - For the powerful open-source project management platform
Anthropic - For Claude and MCP SDK
Community Contributors - For feedback and improvements

📞 Support

Documentation: RUN.md for setup guides
Issues: GitHub Issues
Discussions: GitHub Discussions
Taiga API Docs: https://docs.taiga.io/api.html

Built with ❤️ for the AI-powered project management community

⭐ Star this repo if you find it useful!

⚠️ Disclaimer

This project is not officially affiliated with Taiga. It's a community-driven MCP server implementation for integrating Taiga with LLM applications.