Taiga MCP Server

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

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

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 RUN.md for detailed setup instructions for Claude Desktop and Claude Code.

🛠️ Available Tools

The server exposes 10 tools through the MCP protocol:

Authentication

Project Management

User Story Management

Task Management

* = 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

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

🗺️ 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:

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Make your changes

4. Add tests: Ensure coverage for new code

5. Run quality checks:

   black app/ tests/
   ruff check app/ tests/
   mypy app/
   pytest

6. Commit your changes: git commit -m 'Add amazing feature'

7. Push to branch: git push origin feature/amazing-feature

8. 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.