🚀 Taiga MCP Server

A powerful Model Context Protocol (MCP) server that enables natural language interaction with Taiga project management systems. Seamlessly manage your projects, sprints, user stories, tasks, and issues through conversational AI.

🤖 AI-Powered Development: This project was developed collaboratively with Claude Code (claude.ai/code), showcasing the potential of AI-assisted software development.

✨ Features

📊 Complete Project Management

Projects: List and view project details
Sprints: Create, list, and track sprint progress with detailed statistics
User Stories: Create and manage user stories within projects
Tasks: Create tasks linked to user stories
Issues: Full issue lifecycle management with sprint associations

🔗 Advanced Sprint-Issue Tracking

View issues by sprint with complete relationship mapping
Get detailed issue information including sprint assignments
Track sprint progress with completion statistics
Real-time status updates and progress monitoring

🚀 Batch Operations

Batch Create Issues: Create multiple issues in one operation (up to 20)
Batch Create User Stories: Bulk create user stories with story points
Batch Create Tasks: Mass create tasks for specific user stories
Smart Error Handling: Individual failures don't affect other items
Detailed Reporting: Success/failure status for each item

🔍 Advanced Query Syntax

SQL-like Query Language: Use field:operator:value syntax for precise searches
Logical Operators: Combine conditions with AND, OR, NOT
Text Matching: Fuzzy search, wildcards, and substring matching
Date Ranges: Flexible time-based queries (today, last_week, >7d)
Sorting & Limiting: ORDER BY and LIMIT clauses for result control

💬 Team Collaboration System

Comment Management: Add, view, edit, and delete comments on any work item
Discussion Threads: Complete comment history with user information
Team Communication: Enhanced collaboration through structured discussions
Real-time Updates: Immediate comment synchronization across team

📎 File Attachment Management

Flexible File Upload: Support both file path and Base64 upload methods
Claude Client Integration: Optimized for Claude Desktop file handling
Multi-format Support: Images, documents, PDFs, and all major file types
Smart Path Resolution: Automatic file path detection from common locations
Download Management: Efficient file download with path management
Storage Organization: Clean attachment management with descriptions

🏛️ Epic Management (Enterprise)

Large-scale Organization: Create and manage Epic-level project components
Hierarchical Structure: Link User Stories to Epics for complete project visibility
Progress Tracking: Epic-level progress statistics and completion tracking
Enterprise Planning: Support for roadmap planning and feature releases

📖 Wiki Management (Knowledge Base)

Documentation Hub: Create and manage project Wiki pages for knowledge sharing
Markdown Support: Full Markdown editing with rich content formatting
Flexible Identification: Access pages by ID or user-friendly slug names
Collaboration Features: Watch/unwatch pages for change notifications
Version Control: Automatic versioning prevents edit conflicts
Content Organization: Centralized documentation management per project

💬 Natural Language Interface

"List all projects"
"Show me Sprint 5 progress statistics"
"Create a high-priority bug issue in project X"
"Which issues are assigned to Sprint 3?"
"Get details for issue #123"

🛠️ Installation & Setup

Prerequisites

Node.js (v14 or higher) - Download here
Taiga account with API access

Option 1: NPX (Recommended)

No installation required - runs latest version automatically:

# NPM Registry (official)
npx taiga-mcp-server

# GitHub Package Registry (alternative)
npx @greddy7574/taiga-mcp-server

Option 2: Global Installation

# From NPM Registry
npm install -g taiga-mcp-server
taiga-mcp

# From GitHub Packages
npm install -g @greddy7574/taiga-mcp-server

Option 3: Docker Deployment

# Build the image
docker build -t taiga-mcp-server .

# Run with environment file
docker run --rm -i --env-file .env taiga-mcp-server

# Or with environment variables
docker run --rm -i \
  -e TAIGA_API_URL=https://api.taiga.io/api/v1 \
  -e TAIGA_USERNAME=your_username \
  -e TAIGA_PASSWORD=your_password \
  taiga-mcp-server

# Using docker-compose
docker-compose up --build

⚙️ Configuration

Claude Desktop Integration

NPX Method (Recommended)

Add to your Claude Desktop config.json:

{
  "mcpServers": {
    "taiga-mcp": {
      "command": "npx",
      "args": ["taiga-mcp-server"],
      "env": {
        "TAIGA_API_URL": "https://api.taiga.io/api/v1",
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Docker Method

{
  "mcpServers": {
    "taiga-mcp": {
      "command": "docker",
      "args": [
        "run", 
        "--rm", 
        "-i",
        "-e", "TAIGA_API_URL=https://api.taiga.io/api/v1",
        "-e", "TAIGA_USERNAME=your_username",
        "-e", "TAIGA_PASSWORD=your_password",
        "taiga-mcp-server:latest"
      ]
    }
  }
}

Docker Compose Method

{
  "mcpServers": {
    "taiga-mcp": {
      "command": "docker-compose",
      "args": [
        "-f", "/path/to/project/docker-compose.yml",
        "run", "--rm", "taiga-mcp-server"
      ],
      "cwd": "/path/to/project"
    }
  }
}

Custom Taiga Instance

For self-hosted Taiga instances:

{
  "env": {
    "TAIGA_API_URL": "https://your-taiga-domain.com/api/v1",
    "TAIGA_USERNAME": "your_username",
    "TAIGA_PASSWORD": "your_password"
  }
}

🎯 Usage Examples

Sprint Management

🗣️ "Show me all sprints in project MyApp"
📊 Returns: List of sprints with status and dates

🗣️ "Get detailed statistics for Sprint 5"  
📈 Returns: Progress stats, completion rates, user stories count

🗣️ "Create a new sprint called 'Q1 Release' from 2024-01-01 to 2024-03-31"
✅ Returns: Created sprint details

Issue Tracking

🗣️ "List all issues in project MyApp"
📋 Returns: Issues with sprint assignments and status

🗣️ "Show me issue #123 details"
🔍 Returns: Complete issue info including sprint, assignee, timeline

🗣️ "Update issue 838 status to 'In Progress'"
🔄 Returns: Issue status updated with confirmation

🗣️ "Assign issue 838 to John Doe"
👤 Returns: Issue assigned to team member with details

🗣️ "Add issue 838 to Sprint 1.0.95"
🏃 Returns: Issue moved to sprint with confirmation

🗣️ "Remove issue 838 from sprint"
🏃 Returns: Issue removed from sprint assignment

🗣️ "What issues are in Sprint 3?"
📋 Returns: All issues assigned to that sprint

Project Management

🗣️ "Create a high-priority bug issue: 'Login page not working'"
🐛 Returns: Created issue with details

🗣️ "List all user stories in project MyApp"
📝 Returns: User stories with status and assignments

🗣️ "Create these 5 issues in batch: Bug1, Bug2, Feature1, Task1, Task2"
🚀 Returns: Batch creation results with individual success/failure status

Batch Operations Examples

🗣️ "Batch create these issues in MyApp:
- Bug: Login page broken (High priority)
- Feature: Add search functionality (Medium priority) 
- Task: Update documentation (Low priority)"
📊 Returns: Created 3/3 issues successfully with reference numbers

🗣️ "Batch create user stories:
- User registration flow (5 points)
- Password reset feature (3 points)
- Email notifications (2 points)"
📋 Returns: Created 3/3 user stories with story point assignments

Advanced Query Examples

🗣️ "Find all high priority bugs assigned to john: status:open AND priority:high AND assignee:john AND type:bug"
📊 Returns: Filtered list of critical bugs needing attention

🗣️ "Show user stories with 5+ points created this week: points:>=5 AND created:this_week ORDER BY points DESC"
📈 Returns: High-value stories with detailed point breakdown

🗣️ "Search for API-related tasks: subject:contains:\"API\" OR description:contains:\"API\" LIMIT 10"
🔍 Returns: All tasks mentioning API with relevance ranking

Comment System Examples

🗣️ "Add comment to issue #123: 'This needs more testing before deployment'"
💬 Returns: Comment added successfully with timestamp and user info

🗣️ "Show me all comments for user story #456"
📝 Returns: Complete comment history with user names and dates

🗣️ "Edit comment #789 to say 'Updated implementation approach'"
✏️ Returns: Comment updated successfully with new content

🗣️ "Delete comment #321"
🗑️ Returns: Comment removed from the discussion thread

File Attachment Examples

🗣️ "Upload design.pdf to user story #456 with description 'UI mockup v2'"
📎 Returns: File uploaded successfully with size and metadata

🗣️ "Upload screenshot.png to issue #123 in project MyApp"
📸 Returns: Image file attached with automatic MIME type detection

🗣️ "List all attachments for issue #789"
📂 Returns: Complete attachment list with filenames, sizes, and upload dates

🗣️ "Download attachment #123 to /Downloads/documents/"
⬇️ Returns: File downloaded successfully to specified location

🗣️ "Delete attachment #456"
🗑️ Returns: Attachment removed from the project

File Upload Methods

The system supports two upload methods optimized for different use cases:

Method 1: File Path (Recommended for Claude Desktop)

{
  "itemType": "issue",
  "itemId": 123,
  "projectIdentifier": "MyApp",
  "filePath": "design.pdf",
  "description": "UI mockup v2"
}

Method 2: Base64 Data (For programmatic use)

{
  "itemType": "issue", 
  "itemId": 123,
  "projectIdentifier": "MyApp",
  "fileData": "base64_encoded_file_content",
  "fileName": "design.pdf",
  "mimeType": "application/pdf",
  "description": "UI mockup v2"
}

Epic Management Examples

🗣️ "Create epic 'API v2.0 Migration' in project MyApp with description 'Complete API redesign'"
🏛️ Returns: Epic created with ID, color, and project association

🗣️ "List all epics in project MyApp"
📋 Returns: Epic list with progress stats and linked user stories count

🗣️ "Get details for epic #789"
📊 Returns: Epic overview with progress, status, and linked user stories

🗣️ "Link user story #456 to epic #789"
🔗 Returns: Story successfully linked to epic for better organization

🗣️ "Update epic #789 status to 'In Progress' and add tag 'backend'"
✏️ Returns: Epic updated with new status and organizational tags

Wiki Management Examples

🗣️ "Create wiki page 'api-documentation' in project MyApp with content about API usage"
📖 Returns: Wiki page created with slug, project association, and content preview

🗣️ "List all wiki pages in project MyApp"
📋 Returns: Complete wiki page list with modification dates and content summaries

🗣️ "Get wiki page 'user-guide' details from project MyApp"
🔍 Returns: Full wiki content, metadata, watchers, and version information

🗣️ "Update wiki page 'installation-guide' with new Docker instructions"
✏️ Returns: Wiki page updated with new content and incremented version

🗣️ "Watch wiki page 'api-documentation' for change notifications"
👁️ Returns: Successfully subscribed to wiki page change notifications

🗣️ "Delete wiki page 'outdated-info' from project MyApp"
🗑️ Returns: Wiki page permanently deleted with confirmation details

🔧 Available Tools (42 Total)

🔐 Authentication (1 tool)

Tool	Description
`authenticate`	Authenticate with Taiga API

📁 Project Management (2 tools)

Tool	Description
`listProjects`	Get all accessible projects
`getProject`	View detailed project information

🏃 Sprint Management (4 tools)

Tool	Description
`listMilestones`	List all sprints in a project
`getMilestoneStats`	Get sprint progress and statistics
`createMilestone`	Create new sprints with dates
`getIssuesByMilestone`	View all issues in a sprint

🐛 Issue Management (6 tools)

Tool	Description
`listIssues`	List issues with sprint info
`getIssue`	Get detailed issue information
`createIssue`	Create issues with priorities/types
`updateIssueStatus`	Update issue status (e.g., "In Progress", "Done")
`addIssueToSprint`	Assign issues to sprints or remove from sprints
`assignIssue`	Assign issues to team members or unassign

📝 User Story Management (2 tools)

Tool	Description
`listUserStories`	View user stories in a project
`createUserStory`	Create new user stories

✅ Task Management (1 tool)

Tool	Description
`createTask`	Create tasks linked to user stories

🚀 Batch Operations (3 tools)

Tool	Description
`batchCreateIssues`	Batch create multiple issues (up to 20)
`batchCreateUserStories`	Batch create multiple user stories
`batchCreateTasks`	Batch create multiple tasks for a user story

🔍 Advanced Search (3 tools)

Tool	Description
`advancedSearch`	Execute advanced SQL-like queries
`queryHelp`	Get query syntax help and examples
`validateQuery`	Validate query syntax before execution

💬 Comment System (4 tools)

Tool	Description
`addComment`	Add comments to issues, stories, or tasks
`listComments`	View comment history for items
`editComment`	Edit existing comments
`deleteComment`	Delete comments

📎 File Attachments (4 tools)

Tool	Description	Key Features
`uploadAttachment`	Upload files to issues, stories, or tasks	Dual method support (file path/Base64), smart path resolution
`listAttachments`	View attachment list for items	Complete metadata with file sizes and upload dates
`downloadAttachment`	Download attachments by ID	Flexible download path management
`deleteAttachment`	Delete attachments	Safe deletion with confirmation

🏛️ Epic Management (6 tools)

Tool	Description
`createEpic`	Create large-scale Epic features
`listEpics`	List all Epics in a project
`getEpic`	Get Epic details and progress stats
`updateEpic`	Update Epic information and status
`linkStoryToEpic`	Link User Stories to Epics
`unlinkStoryFromEpic`	Remove Story-Epic associations

📖 Wiki Management (6 tools)

Tool	Description
`createWikiPage`	Create project Wiki pages with Markdown support
`listWikiPages`	List all Wiki pages in a project
`getWikiPage`	Get Wiki page details by ID or slug
`updateWikiPage`	Update Wiki page content and settings
`deleteWikiPage`	Delete Wiki pages (irreversible)
`watchWikiPage`	Watch/unwatch Wiki pages for notifications

🚀 Why Choose Taiga MCP Server?

🔥 Zero Setup: Works immediately with npx
🧠 AI-Native: Built specifically for conversational project management
🔗 Complete Integration: Full Taiga API coverage with 39 tools
📊 Rich Data: Detailed progress tracking and statistics
🎯 Sprint-Focused: Advanced sprint-issue relationship tracking
🛡️ Secure: Environment-based credential management
🚀 Batch Operations: Efficient bulk operations for large projects
💬 Team Collaboration: Complete comment system for enhanced communication
📎 File Management: Dual upload methods (file path/Base64) with Claude Desktop optimization
🏛️ Enterprise-Ready: Epic management for large-scale project organization
📖 Knowledge Management: Complete Wiki system for project documentation
🔍 Advanced Search: SQL-like query syntax for complex data filtering

🙏 Acknowledgments

Attribution and Legal Notice

This project was inspired by mcpTAIGA by adriapedralbes. This version represents a substantial rewrite and reimplementation with entirely new architecture, features, and functionality while using the same ISC license terms.

AI-Assisted Development

🤖 Developed with Claude Code: This entire project was collaboratively developed with Claude Code, demonstrating the power of AI-assisted software development. The architecture, implementation, testing, and documentation were all created through human-AI collaboration.

Key Enhancements

From the original basic concept, this version expanded to include:

Complete Architectural Redesign: Professional modular tool system (v1.5.0+)
33 MCP Tools: From basic functionality to enterprise-grade project management
Advanced Sprint Management: Complete milestone tracking with detailed statistics
Enhanced Issue Management: Full issue lifecycle with sprint associations
Batch Operations: Efficient bulk creation for large-scale projects (v1.6.0)
Advanced Query System: SQL-like syntax for complex data filtering (v1.6.1)
Team Collaboration: Complete comment system for enhanced communication (v1.7.0)
File Management: Full attachment lifecycle with multi-format support (v1.7.1)
Epic Management: Enterprise-grade large-scale project organization (v1.8.0)
Professional Code Quality: Error handling, formatting, comprehensive testing
Comprehensive Documentation: Professional guides and examples in 3 languages
Automated CI/CD: Dual registry publishing with complete automation

Original concept: Basic Taiga MCP connectivity
This implementation: Full-featured Taiga project management suite with entirely new architecture

This reimplementation acknowledges the foundational concept while showcasing the collaborative potential of AI-assisted software development.

📚 Documentation

Complete documentation is available on our GitHub Wiki 📖

🌐 Multi-Language Support

Our documentation is available in three languages:

🇺🇸 English - Complete English documentation
🇨🇳 简体中文 - 完整的简体中文文档
🇹🇼 繁體中文 - 完整的繁體中文文件

🎯 Quick Navigation

Section	English	简体中文	繁體中文
Getting Started	Installation Guide	安装指南	安裝指南
API Reference	API Reference	API 参考	API 參考
Architecture	Architecture	架构概览	架構概覽
CI/CD Guide	CI/CD Guide	CI/CD 指南	CI/CD 指南

👩‍💻 Developer Resources

Topic	English	简体中文	繁體中文
Design Document	Design	设计文档	設計文件
First Steps	First Steps	第一步	第一步
Configuration	Configuration	配置说明	設定說明

💡 Tip: The Wiki provides better search, navigation, and mobile experience!

🚀 Automated Publishing

This project features a fully automated CI/CD pipeline:

npm version patch              # Create new version
git push origin main --tags    # Trigger automated publishing

Automated Flow: Tests → NPM Publish → GitHub Packages → Release Creation
Dual Registry Support: Available on both NPM and GitHub Package Registry
Full Documentation: See CI/CD Guide for complete setup

🤝 Contributing

Issues and pull requests are welcome! Please visit our GitHub repository to contribute.

📄 License

ISC License - This project is licensed under the ISC License, same as the original mcpTAIGA.

Project Information

Original Inspiration: adriapedralbes / mcpTAIGA
This Implementation: Substantial rewrite by greddy7574@gmail.com with AI assistance from Claude Code
License: ISC License
Architecture: Entirely new modular design with 33 MCP tools across 11 categories
Current Version: v1.8.0 - Enterprise Integration Edition with Epic Management

Enhanced with ❤️ for agile teams using Taiga project management

Taiga MCP Server