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

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

🛠️ 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, status, tags* | | listUserStories | List stories with pagination | projectIdentifier, pageSize, page, fetchAll* | | getUserStory | Get story details | userStoryIdentifier, projectIdentifier* | | updateUserStory | Update existing story | userStoryIdentifier, projectIdentifier, subject, description, status, assignedTo, tags, points, dueDate |

Task Management

| Tool | Description | Parameters | |------|-------------|------------| | createTask | Create task in story | projectIdentifier, userStoryIdentifier, subject, description, status, 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 ✅

[x] Authentication & token management
[x] Project listing and details
[x] User story CRUD operations
[x] Task management
[x] Team member listing
[x] Smart pagination
[x] 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.