Taiga MCP Server

---

📋 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 ✅

• [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:

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

---

---

⚠️ Disclaimer

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