Taiga MCP Bridge

Community fork of talhaorak/pytaiga-mcp with additional features, CI/CD, and ongoing maintenance.

Overview

The Taiga MCP Bridge is a powerful integration layer that connects Taiga project management platform with the Model Context Protocol (MCP), enabling AI tools and workflows to interact seamlessly with Taiga's resources.

This bridge provides a comprehensive set of tools and resources for AI agents to:

• Create and manage projects, epics, user stories, tasks, and issues in Taiga
• Track sprints and milestones
• Assign and update work items
• Query detailed information about project artifacts
• Manage project members and permissions

By using the MCP standard, this bridge allows AI systems to maintain contextual awareness about project state and perform complex project management tasks programmatically.

Features

Comprehensive Resource Support

The bridge supports the following Taiga resources with complete CRUD operations:

• Projects: Create, update, and manage project settings and metadata
• Epics: Manage large features that span multiple sprints
• User Stories: Handle detailed requirements and acceptance criteria
• Tasks: Track smaller units of work within user stories
• Issues: Manage bugs, questions, and enhancement requests
• Sprints (Milestones): Plan and track work in time-boxed intervals

Security & Configuration

• Secure Credentials: Environment variable authentication with credential protection - passwords never appear in logs or error messages
• Auto-Authentication: Configure TAIGA_USERNAME and TAIGA_PASSWORD environment variables for seamless startup without manual login
• Input Validation: Allowlist-based parameter validation prevents unexpected data from reaching the Taiga API

Response Filtering

All tools support a verbosity parameter to control response size, reducing AI context usage:

Level	Description	Use Case
minimal	Core fields only (id, ref, subject, status, project)	Listing many items
standard	Common fields including version for updates (default)	Normal operations
full	Complete API response	Debugging, full details

Example:

# Get minimal response for efficient context usage
stories = client.call_tool("list_user_stories", {
    "project_id": 123,
    "verbosity": "minimal"
})
# Returns: [{"id": 1, "ref": 42, "subject": "...", "status": 1, "project": 123}, ...]

Installation

This project uses uv for fast, reliable Python package management.

Prerequisites

• Python 3.12 or higher
• uv package manager

Basic Installation

# Clone the repository
git clone https://github.com/TETRA-2023/pytaiga-mcp.git
cd pytaiga-mcp

# Install dependencies
./install.sh

Development Installation

For development (includes testing and code quality tools):

./install.sh --dev

Manual Installation

If you prefer to install manually:

# Production dependencies only
uv pip install -e .

# With development dependencies
uv pip install -e ".[dev]"

Docker

Pull the pre-built image from GHCR:

docker pull ghcr.io/tetra-2023/pytaiga-mcp:latest

Or build locally:

docker build -t pytaiga-mcp .

Run with environment variables:

docker run -i --rm \
  -e TAIGA_API_URL=https://your-taiga-instance.com \
  -e TAIGA_USERNAME=your_username \
  -e TAIGA_PASSWORD=your_password \
  ghcr.io/tetra-2023/pytaiga-mcp:latest

To use SSE transport instead of stdio, append --sse:

docker run --rm \
  -e TAIGA_API_URL=https://your-taiga-instance.com \
  -e TAIGA_USERNAME=your_username \
  -e TAIGA_PASSWORD=your_password \
  -p 8000:8000 \
  ghcr.io/tetra-2023/pytaiga-mcp:latest --sse

Example MCP client configuration (.mcp.json) for stdio transport:

{
  "mcpServers": {
    "taigaApi": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TAIGA_API_URL",
        "-e", "TAIGA_USERNAME",
        "-e", "TAIGA_PASSWORD",
        "ghcr.io/tetra-2023/pytaiga-mcp:latest"
      ]
    }
  }
}

Note: Use -i (interactive) without -t (pseudo-TTY) for stdio transport. The -e VAR form (without =value) forwards the variable from your host environment.

Configuration

The bridge can be configured through environment variables or a .env file:

Environment Variable	Description	Default
TAIGA_API_URL	Base URL for the Taiga API	http://localhost:9000
TAIGA_USERNAME	Taiga username for auto-authentication	(none)
TAIGA_PASSWORD	Taiga password for auto-authentication	(none)
TAIGA_TRANSPORT	Transport mode (stdio or sse)	stdio
LOG_LEVEL	Logging level	INFO

Create a .env file in the project root to set these values:

TAIGA_API_URL=https://api.taiga.io/api/v1/
TAIGA_USERNAME=your_username
TAIGA_PASSWORD=your_password
TAIGA_TRANSPORT=stdio
LOG_LEVEL=INFO

Security Note: Credentials are protected and will never appear in logs, error messages, or stack traces. When TAIGA_USERNAME and TAIGA_PASSWORD are configured, the server auto-authenticates on startup - no manual login required.

Usage

With stdio mode

Paste the following json in your Claude App's or Cursor's mcp settings section.

Recommended: Set credentials via environment variables in your shell profile rather than in config files to avoid exposing them in plaintext.

{
    "mcpServers": {
        "taigaApi": {
            "command": "uv",
            "args": [
                "--directory",
                "<path to local pyTaigaMCP folder>",
                "run",
                "src/server.py"
            ],
            "env": {
                "TAIGA_TRANSPORT": "<stdio|sse>",                
                "TAIGA_API_URL": "<Taiga API Url (ex: http://localhost:9000)",
                "TAIGA_USERNAME": "<taiga username>",
                "TAIGA_PASSWORD": "<taiga password>"
            }
        }
}

Running the Bridge

Start the MCP server with:

# Default stdio transport
./run.sh

# For SSE transport
./run.sh --sse

Or manually:

# For stdio transport (default)
uv run python src/server.py

# For SSE transport
uv run python src/server.py --sse

Transport Modes

The server supports two transport modes:

1. stdio (Standard Input/Output) - Default mode for terminal-based clients
2. SSE (Server-Sent Events) - Web-based transport with server push capabilities

You can set the transport mode in several ways:

• Using the --sse flag with run.sh or server.py (default is stdio)
• Setting the TAIGA_TRANSPORT environment variable
• Adding TAIGA_TRANSPORT=sse to your .env file

Authentication Flow

Auto-Authentication (Recommended)

If TAIGA_USERNAME and TAIGA_PASSWORD environment variables are set, the server automatically authenticates on startup. You can omit session_id from tool calls to use the default session:

# No login needed - uses auto-authenticated default session
projects = client.call_tool("list_projects", {})
stories = client.call_tool("list_user_stories", {"project_id": 123})
new_story = client.call_tool("create_user_story", {
    "project_id": 123,
    "subject": "New feature request"
})

Manual Session Management

For scenarios requiring multiple sessions or explicit control, use the session-based model:

1. Login: Authenticate using the login tool:

   session = client.call_tool("login", {
       "username": "your_taiga_username",
       "password": "your_taiga_password",
       "host": "https://api.taiga.io" # Optional
   })
   # Save the session_id from the response
   session_id = session["session_id"]
   

2. Using Tools and Resources: Include the session_id in every API call:

   # For resources, include session_id in the URI
   projects = client.get_resource(f"taiga://projects?session_id={session_id}")
   
   # For project-specific resources
   epics = client.get_resource(f"taiga://projects/123/epics?session_id={session_id}")
   
   # For tools, include session_id as a parameter
   new_project = client.call_tool("create_project", {
       "session_id": session_id,
       "name": "New Project",
       "description": "Description"
   })
   

3. Check Session Status: You can check if your session is still valid:

   status = client.call_tool("session_status", {"session_id": session_id})
   # Returns information about session validity and remaining time
   

4. Logout: When finished, you can logout to terminate the session:

   client.call_tool("logout", {"session_id": session_id})
   

Example: Complete Project Creation Workflow

Here's a complete example of creating a project with epics and user stories:

from mcp.client import Client

# Initialize MCP client
client = Client()

# Authenticate and get session ID
auth_result = client.call_tool("login", {
    "username": "admin",
    "password": "password123",
    "host": "https://taiga.mycompany.com"
})
session_id = auth_result["session_id"]

# Create a new project
project = client.call_tool("create_project", {
    "session_id": session_id,
    "name": "My New Project",
    "description": "A test project created via MCP"
})
project_id = project["id"]

# Create an epic
epic = client.call_tool("create_epic", {
    "session_id": session_id,
    "project_id": project_id,
    "subject": "User Authentication",
    "description": "Implement user authentication features"
})
epic_id = epic["id"]

# Create a user story in the epic
story = client.call_tool("create_user_story", {
    "session_id": session_id,
    "project_id": project_id,
    "subject": "User Login",
    "description": "As a user, I want to log in with my credentials",
    "epic_id": epic_id
})

# Logout when done
client.call_tool("logout", {"session_id": session_id})

Development

Project Structure

pytaiga-mcp/
├── src/
│   ├── server.py          # MCP server implementation with tools
│   ├── taiga_client.py    # Taiga API client wrapper
│   └── config.py          # Configuration settings with Pydantic
├── tests/
│   ├── test_server.py     # Unit tests
│   └── test_integration.py # Integration tests
├── .github/workflows/
│   └── ci.yml             # CI pipeline (test, lint, Docker, release)
├── .pre-commit-config.yaml # Pre-commit hooks (ruff, pytest)
├── Dockerfile             # Container image definition
├── pyproject.toml         # Project configuration and dependencies
├── install.sh             # Installation script
├── run.sh                 # Server execution script
└── README.md              # Project documentation

Testing

Pre-commit hooks run automatically on each commit (ruff lint, ruff format, unit tests). To run manually:

# Run pre-commit hooks on all files
uv run pre-commit run --all-files

# Run tests directly
uv run pytest tests/test_server.py -v --tb=short

# Run with coverage reporting
uv run pytest --cov=src

Debugging and Inspection

Use the included inspector tool for debugging:

# Default stdio transport
./inspect.sh

# For SSE transport
./inspect.sh --sse

# For development mode
./inspect.sh --dev

Error Handling

All API operations return standardized error responses in the following format:

{
  "status": "error",
  "error_type": "ExceptionClassName",
  "message": "Detailed error message"
}

Planned Features

The following features are planned for future releases:

• Session expiration and automatic cleanup
• Rate limiting for API calls
• Retry mechanism with exponential backoff
• Connection pooling

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Install development dependencies (./install.sh --dev)
4. Set up pre-commit hooks (uv run pre-commit install)
5. Make your changes
6. Commit your changes — pre-commit hooks will run linting and tests automatically
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Taiga for their excellent project management platform
• Model Context Protocol (MCP) for the standardized AI communication framework
• All contributors who have helped shape this project