Taiga MCP Bridge

Interact with the Taiga project management platform through an MCP bridge, allowing AI tools to manage project resources.

Community forkoftalhaorak/pytaiga-mcpwith additional features, CI/CD, and ongoing maintenance.

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

# 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}, ...]

This project usesuvfor fast, reliable Python package management.

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

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

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

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 VARform (without=value) forwards the variable from your host environment.

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

Create a.envfile 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. WhenTAIGA_USERNAMEandTAIGA_PASSWORDare configured, the server auto-authenticates on startup - no manual login required.

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>" } } }

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

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

The server supports two transport modes:
- stdio (Standard Input/Output)- Default mode for terminal-based clients
- SSE (Server-Sent Events)- Web-based transport with server push capabilities

You can set the transport mode in several ways:

- Using the--sseflag with run.sh or server.py (default is stdio)
- Setting theTAIGA_TRANSPORTenvironment variable
- AddingTAIGA_TRANSPORT=sseto your.envfile

IfTAIGA_USERNAMEandTAIGA_PASSWORDenvironment variables are set, the server automatically authenticates on startup. You can omitsession_idfrom 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" })

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

Login: Authenticate using thelogintool:

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"]

Using Tools and Resources: Include thesession_idin 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" })

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

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})

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

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

Use the included inspector tool for debugging:

# Default stdio transport ./inspect.sh # For SSE transport ./inspect.sh --sse # For development mode ./inspect.sh --dev

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

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

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

Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (git checkout -b feature/amazing-feature)
- Install development dependencies (./install.sh --dev)
- Set up pre-commit hooks (uv run pre-commit install)
- Make your changes
- Commit your changes — pre-commit hooks will run linting and tests automatically
- Push to the branch (git push origin feature/amazing-feature)
- Open a Pull Request

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

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

Interact with task, doc, and project data in Dart, an AI-native project management tool