Skip to content

Gira MCP Server

The Gira MCP (Model Context Protocol) server enables AI agents like Claude to interact directly with your Gira projects, providing seamless project management capabilities through natural language commands.

🎯 What is the Gira MCP Server?

The Gira MCP server is a Model Context Protocol implementation that exposes 30 powerful tools for managing tickets, epics, sprints, and boards. It allows AI agents to:

  • Create and manage tickets with full lifecycle support
  • Organize work with epics and track progress across initiatives
  • Plan and execute sprints with comprehensive sprint management
  • Visualize project state with enhanced board views and analytics
  • Maintain data integrity through built-in validation and security controls

⚡ Quick Start

Prerequisites

  • Python 3.8 or higher
  • An initialized Gira project (gira init "My Project")
  • Claude Desktop (recommended) or another MCP client

Installation

# Install Gira with MCP support
pip install "gira[mcp]"

# Or from source with MCP dependencies
pip install -e ".[mcp]"

Claude Desktop Configuration

  1. Add to Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
  "mcpServers": {
    "gira": {
      "command": "python",
      "args": ["-m", "gira.mcp.server"],
      "env": {
        "GIRA_MCP_WORKING_DIRECTORY": "/path/to/your/gira/project"
      }
    }
  }
}

  1. Restart Claude Desktop

  2. Start using Gira with Claude:

  3. "List all open tickets"
  4. "Create a bug ticket for login issue"
  5. "Show me the current sprint progress"
  6. "Move ticket GCM-123 to done"

🛠️ Available Tools

The Gira MCP server provides 30 specialized tools organized into four categories:

🎫 Ticket Management (12 tools)

  • list_tickets - List and filter tickets with advanced search
  • get_ticket - Get detailed ticket information
  • create_ticket - Create new tickets with full metadata
  • update_ticket - Update ticket fields and properties
  • move_ticket - Move tickets between statuses
  • delete_ticket - Remove tickets (with safety checks)
  • add_comment - Add comments to tickets
  • assign_ticket - Assign tickets to team members
  • estimate_ticket - Set story points and estimates
  • link_tickets - Create dependencies between tickets
  • search_tickets - Advanced full-text search across tickets
  • bulk_update_tickets - Update multiple tickets efficiently

🎯 Epic Management (7 tools)

  • list_epics - List and filter epics
  • get_epic - Get detailed epic information
  • create_epic - Create new epics
  • update_epic - Update epic properties
  • add_tickets_to_epic - Associate tickets with epics
  • remove_tickets_from_epic - Remove tickets from epics
  • get_epic_progress - Track epic completion status

🏃‍♂️ Sprint Management (8 tools)

  • list_sprints - List and filter sprints
  • get_sprint - Get detailed sprint information
  • create_sprint - Create new sprints with goals and timelines
  • update_sprint - Update sprint properties
  • start_sprint - Activate sprint and begin tracking
  • complete_sprint - Close sprint and generate reports
  • assign_tickets_to_sprint - Add tickets to sprint backlog
  • get_sprint_metrics - Analyze sprint velocity and burndown

📊 Board & Visualization (3 tools)

  • get_enhanced_board_state - Get comprehensive board view with analytics
  • get_swimlane_tickets - Get tickets organized by epic or assignee
  • move_tickets_bulk - Move multiple tickets between statuses efficiently

🔒 Security & Safety

The Gira MCP server implements multiple security layers:

  • 🛡️ Working Directory Validation - Operations are restricted to your Gira project
  • ⚠️ Consent Mechanisms - Configurable confirmation for destructive operations
  • 📝 Audit Logging - All operations are logged for transparency
  • 🚦 Rate Limiting - Prevents accidental bulk operations
  • 🔍 Input Validation - All parameters are validated before execution

See Security Documentation for detailed security information.

📚 Documentation

Getting Started

Tool References

  • Ticket Tools - Complete reference for all 12 ticket management tools
  • Epic Tools - Complete reference for all 7 epic management tools
  • Sprint Tools - Complete reference for all 8 sprint management tools
  • Board Tools - Complete reference for all 3 board visualization tools

Security & Best Practices

  • Security Model - Security mechanisms, consent levels, and best practices

Examples & Integration

Development

🤖 Example Workflows

Daily Standup Assistant

"Show me all tickets assigned to the team that are in progress or recently completed"
"Create a summary of yesterday's accomplishments for standup"

Sprint Planning

"List all tickets in the backlog that are high priority and unestimated"
"Create a new sprint for the next 2 weeks and add the top 5 backlog items"
"Show me the team's velocity over the last 3 sprints"

Bug Triage

"List all open bug tickets sorted by priority"
"Create a critical bug ticket for the login failure reported by users"
"Assign all unassigned bugs to the appropriate team members"

Release Management

"Show me all tickets in the current sprint that are marked as done"
"Move all completed tickets to the done column and update their status"
"Generate a release summary with all features delivered this sprint"

🆘 Troubleshooting

Common Issues

"No MCP server found" - Ensure Claude Desktop configuration is correct - Verify the working directory path exists and contains a .gira folder - Check that Gira is installed with MCP dependencies: pip install "gira[mcp]"

"Permission denied" errors
- Verify the working directory is writable - Check that the user has permission to read/write Gira project files - Ensure no files are locked by other processes

"Tool not found" errors - Restart Claude Desktop after configuration changes - Verify all 30 tools are registered by checking server logs - Check for any import errors in the server initialization

For more troubleshooting information, see the Installation Guide.

Ready to get started? Follow the Installation Guide to set up the Gira MCP server with Claude Desktop.