README

An MCP (Model Context Protocol) server that integrates Redmine with AI assistants like Claude Desktop, enabling natural language interaction with your Redmine instance.

🚀 Quick Start

1. Installation

Via Composer (Recommended):

composer create-project guiziweb/mcp-redmine --stability=dev

Via Git (For Development):

git clone https://github.com/guiziweb/mcp-redmine.git
cd mcp-redmine
composer install

2. Configuration

💡 Get your Redmine API key: Go to Redmine → My account → API access key → Show

For Claude Desktop (Recommended - Simple Setup):

Create a .mcp.json file in your project directory. See MCP Setup Guide for detailed instructions.

{
  "mcpServers": {
    "redmine": {
      "command": "php",
      "args": ["bin/console", "mcp:server"],
      "cwd": "/absolute/path/to/mcp-redmine",
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

⚠️ Important: Replace /absolute/path/to/mcp-redmine with the full path to your project directory.

3. Restart Your AI Assistant

Close and restart your MCP client (Claude Desktop, Cursor, etc.).

✨ Features

Available Tools

Smart Features

• Date Intelligence: "Show my time for last month", "August 2025 entries"
• Smart Summaries: Automatic totals, weekly/daily breakdowns
• Work Analysis: Hours per day, project breakdowns, weekly patterns
• Caching: Projects and activities cached for performance

🛠 Development

Requirements

• PHP 8.2+
• Composer
• Access to a Redmine instance with API enabled

Testing

# Run all tests
composer test

# Run specific test
vendor/bin/phpunit tests/Tools/ListProjectsToolTest.php

# Run with coverage
vendor/bin/phpunit --coverage-html coverage

Code Quality

# Static analysis
vendor/bin/phpstan analyze

# Code style
vendor/bin/php-cs-fixer fix

Architecture

graph TD
    A[AI Assistant<br/>Claude Desktop/Cursor] -->|MCP Protocol| B[MCP Server]
    
    subgraph "MCP Tools Layer - src/Tools/"
        B --> C[ListProjectsTool]
        B --> D[ListIssuesTool] 
        B --> E[LogTimeTool]
        B --> F[ListTimeEntriesTool]
        B --> G[ListTimeActivitiesTool]
        B --> H[AbstractMcpTool]
    end
    
    subgraph "Client Layer - src/Client/"
        C --> I[ProjectClient]
        D --> J[IssueClient]
        E --> K[TimeEntryClient]
        F --> K
        G --> K
        L[UserClient]
        I -.->|Cache 24h| M[CachedProjectClient]
        K -.->|Cache 10min| N[CachedTimeEntryClient]
    end
    
    subgraph "API Layer - src/Api/"
        I --> O[RedmineService]
        J --> O
        K --> O
        L --> O
        O -->|HTTP REST API| P[Redmine Server]
    end
    
    subgraph "Supporting - src/"
        Q[Dto/<br/>Data Transfer Objects] 
        R[Exception/<br/>Custom Exceptions]
        S[Repository/<br/>Domain Layer]
        T[SchemaGenerator.php<br/>JSON Schema]
        U[Kernel.php<br/>Symfony Kernel]
    end
    
    style A fill:#e1f5fe
    style P fill:#ffebee
    style B fill:#f3e5f5
    style M fill:#fff3e0
    style N fill:#fff3e0

📚 Usage Examples

Project Management

User: "List all my Redmine projects"
AI: Shows formatted list of projects with IDs and names

User: "Show me issues from project 'Mobile App'"
AI: Lists all issues from the specified project

Time Tracking

User: "Show my time entries for August 2025"
AI: Displays time entries with daily/weekly totals and work analysis

User: "Log 3.5 hours of testing to issue #456"  
AI: Logs time entry with Testing activity to the specified issue

Smart Analysis

User: "How many hours did I work last week?"
AI: Calculates and shows weekly totals with breakdown

User: "What's my daily average this month?"
AI: Shows monthly progress with hours per day analysis

🔧 Configuration Options

Cache Settings

• Projects: 24 hours (rarely change)
• Activities:24 hours (rarely change)
• Issues: No cache (change frequently)
• Time entries: No cache (real-time data)

🚨 Security

• ✅ Environment-based configuration
• ✅ Validation on all inputs
• ✅ Error handling without data exposure

🐛 Troubleshooting

Common Issues

1. "No tools available"

   • Check MCP configuration file path
   • Verify PHP is in PATH
   • Restart your AI assistant

2. "Authentication failed"

   • Verify REDMINE_URL and REDMINE_API_KEY
   • Check API key permissions in Redmine
   • Ensure API is enabled in Redmine settings

3. "Command not found"

   • Check cwd path in MCP config
   • Verify composer install was run
   • Check file permissions

🔗 Related

• Model Context Protocol
• Claude Desktop
• Redmine API Documentation