Gira MCP Server Installation Guide¶

This guide will walk you through installing and configuring the Gira MCP server for use with Claude Desktop and other MCP clients.

📋 Prerequisites¶

Before installing the Gira MCP server, ensure you have:

Python 3.8 or higher - Check with python --version
An initialized Gira project - Run gira init "My Project" in your project directory
Claude Desktop (recommended) or another MCP-compatible client

🚀 Installation Methods¶

Method 1: Install from PyPI (Recommended)¶

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

# Verify installation
python -m gira.mcp.server --version

Method 2: Install from Source¶

# Clone the repository
git clone https://github.com/goatbytes/gira.git
cd gira

# Install in development mode with MCP dependencies
pip install -e ".[mcp,dev]"

# Verify installation  
python -m gira.mcp.server --version

Method 3: Using uv (Fast Python Package Manager)¶

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

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

🔧 Claude Desktop Configuration¶

Step 1: Locate Configuration File¶

The Claude Desktop configuration file is located at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

Step 2: Basic Configuration¶

Add the Gira MCP server to your Claude Desktop configuration:

{
  "mcpServers": {
    "gira": {
      "command": "python",
      "args": ["-m", "gira.mcp.server"],
      "env": {
        "GIRA_MCP_WORKING_DIRECTORY": "/path/to/your/gira/project"
      }
    }
  }
}

Important: Replace /path/to/your/gira/project with the actual path to your Gira project directory (the one containing the .gira folder).

Step 3: Advanced Configuration Options¶

For more control over the MCP server behavior:

{
  "mcpServers": {
    "gira": {
      "command": "python",
      "args": ["-m", "gira.mcp.server"],
      "env": {
        "GIRA_MCP_WORKING_DIRECTORY": "/path/to/your/gira/project",
        "GIRA_MCP_DRY_RUN": "false",
        "GIRA_MCP_REQUIRE_CONFIRMATION": "true",
        "GIRA_MCP_TRANSPORT": "stdio",
        "GIRA_MCP_LOG_LEVEL": "INFO",
        "GIRA_MCP_AUDIT_ENABLED": "true"
      }
    }
  }
}

Step 4: Multiple Projects Configuration¶

To work with multiple Gira projects, create separate server instances:

{
  "mcpServers": {
    "gira-project-a": {
      "command": "python",
      "args": ["-m", "gira.mcp.server"],
      "env": {
        "GIRA_MCP_WORKING_DIRECTORY": "/path/to/project-a",
        "GIRA_MCP_NAME": "Project A Gira"
      }
    },
    "gira-project-b": {
      "command": "python", 
      "args": ["-m", "gira.mcp.server"],
      "env": {
        "GIRA_MCP_WORKING_DIRECTORY": "/path/to/project-b",
        "GIRA_MCP_NAME": "Project B Gira"
      }
    }
  }
}

Step 5: Restart Claude Desktop¶

After making configuration changes:

Quit Claude Desktop completely
Wait a few seconds
Restart Claude Desktop
Verify the connection by asking Claude: "What Gira tools are available?"

🐍 Python Virtual Environment Setup¶

For better dependency isolation, use a virtual environment:

Using venv¶

# Create virtual environment
python -m venv gira-mcp-env

# Activate it
source gira-mcp-env/bin/activate  # macOS/Linux
# or
gira-mcp-env\Scripts\activate.bat  # Windows

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

# Update Claude Desktop config to use the virtual environment

Then update your Claude Desktop configuration to use the virtual environment Python:

{
  "mcpServers": {
    "gira": {
      "command": "/path/to/gira-mcp-env/bin/python",
      "args": ["-m", "gira.mcp.server"],
      "env": {
        "GIRA_MCP_WORKING_DIRECTORY": "/path/to/your/gira/project"
      }
    }
  }
}

Using conda¶

# Create conda environment
conda create -n gira-mcp python=3.11
conda activate gira-mcp

# Install Gira
pip install "gira[mcp]"

# Use conda environment in Claude Desktop config

🔍 Verification & Testing¶

Test MCP Server Directly¶

# Test server startup (should exit cleanly)
python -m gira.mcp.server --dry-run

# Check server info
python -c "
from gira.mcp.server import create_mcp_server
server = create_mcp_server()
print(f'Server initialized with working directory: {server.config.working_directory}')
"

Test with Claude Desktop¶

Open Claude Desktop
Ask: "What Gira tools do you have available?"
Expected response: Claude should list the 30 available Gira tools
Test a simple command: "List all tickets"

Verify Tool Registration¶

# Check that all 30 tools are registered
python -c "
import sys
sys.path.append('src')
from gira.mcp.server import create_mcp_server
server = create_mcp_server()
print(f'Registered {len(server._tools)} tools')
for tool_name in sorted(server._tools.keys()):
    print(f'  - {tool_name}')
"

🛠️ Alternative MCP Clients¶

MCP Inspector (Development/Testing)¶

# Install MCP Inspector
pip install mcp-inspector

# Test Gira MCP server
mcp-inspector python -m gira.mcp.server

Custom MCP Client¶

import asyncio
from mcp_client import MCPClient

async def test_gira_mcp():
    client = MCPClient()
    await client.connect("python", ["-m", "gira.mcp.server"])

    # List available tools
    tools = await client.list_tools()
    print(f"Available tools: {len(tools)}")

    # Test a tool
    result = await client.call_tool("list_tickets", {})
    print(f"Tickets: {result}")

# Run the test
asyncio.run(test_gira_mcp())

🐛 Troubleshooting¶

Common Issues¶

"ModuleNotFoundError: No module named 'gira.mcp'"¶

Solution: Install MCP dependencies

pip install "gira[mcp]"
# or
pip install fastmcp pydantic pydantic-settings

"No Gira project found in working directory"¶

Solution: Ensure your working directory contains a .gira folder

# Check if .gira exists
ls -la /path/to/your/project/.gira

# If not, initialize Gira project
cd /path/to/your/project
gira init "My Project"

"Permission denied" when accessing project files¶

Solution: Check file permissions

# Check permissions
ls -la /path/to/your/project/.gira

# Fix permissions if needed
chmod -R u+rw /path/to/your/project/.gira

Claude Desktop not recognizing MCP server¶

Solution: Verify configuration and restart

# Validate JSON configuration
python -c "import json; print(json.load(open('/path/to/claude_desktop_config.json')))"

# Check server can start
python -m gira.mcp.server --dry-run

# Restart Claude Desktop completely

"Tool not found" errors in Claude¶

Solution: Check tool registration

# Verify all tools are registered
python -c "
from gira.mcp.server import create_mcp_server
server = create_mcp_server()
print('Registered tools:', len(server._tools))
"

Environment variables not being recognized¶

Solution: Check environment variable format

{
  "mcpServers": {
    "gira": {
      "command": "python",
      "args": ["-m", "gira.mcp.server"], 
      "env": {
        "GIRA_MCP_LOG_LEVEL": "DEBUG"  
      }
    }
  }
}

Debug Mode¶

Enable debug logging for troubleshooting:

{
  "mcpServers": {
    "gira": {
      "command": "python",
      "args": ["-m", "gira.mcp.server"],
      "env": {
        "GIRA_MCP_WORKING_DIRECTORY": "/path/to/your/project",
        "GIRA_MCP_LOG_LEVEL": "DEBUG",
        "GIRA_MCP_ENABLE_DEBUG": "true"
      }
    }
  }
}

Check the debug output in: - Claude Desktop console (if available) - Terminal (when testing server directly) - Audit log file (gira-mcp-audit.log in project directory)

Getting Help¶

If you're still having issues:

Check the logs: Look for error messages in Claude Desktop or server output
Verify prerequisites: Ensure Python version and Gira project setup
Test incrementally: Start with basic server startup, then add complexity
Check permissions: Ensure all files and directories are accessible
Update dependencies: Make sure you have the latest version of Gira and dependencies

For additional support, check the Configuration Reference or review the Security Model for permission-related issues.

✅ Next Steps¶

Once installation is complete:

Read the Tool References to understand available functionality
Explore Example Workflows for inspiration
Review Security Settings to configure appropriate safety measures
Try the Claude Desktop Integration Examples for real-world usage patterns

Installation complete! You're now ready to use AI-powered project management with Gira.