Redmine MCP Server

A Model Context Protocol (MCP) server for Redmine integration, enabling Claude Code to directly interact with Redmine project management systems.

🚀 Features

✅ Issue Management

• Query Issues: Get detailed issue information and lists

• Create Issues: Create new issues and set related attributes

• Update Issues: Modify issue content, status, priority, etc.

• Assign Issues: Assign or unassign issues to specific users

• Add Notes: Add public or private notes to issues

• Close Issues: Automatically set issues to completed status

✅ Project Management

• Project Lists: Get accessible project lists

• Project Issues: Filter by status and list all issues in projects

✅ Search Features

• Keyword Search: Search for keywords in issue titles and descriptions

• My Issues: Quick view of issues assigned to current user

✅ System Tools

• Health Check: Verify MCP server and Redmine connection status

• Status Query: Get available issue status lists

Related MCP server: Linear MCP Server

📋 System Requirements

• Python: 3.12 or higher

• Redmine: Version with REST API support (recommended 4.0+)

• Package Manager: uv or pip

🔧 Installation & Setup

1. Clone the Project

2. Install Dependencies

Using uv (recommended):

Or using pip:

3. Environment Configuration

Create a .env file:

Edit the .env file and set the following environment variables:

Environment Variables Reference

Log Level Priority:

1. REDMINE_MCP_LOG_LEVEL (highest priority - project-specific)

2. LOG_LEVEL (backward compatibility)

3. INFO (default if neither is set)

Note: The system automatically handles case conversion and ensures FastMCP compatibility.

4. Redmine API Setup

4.1 Enable REST API

1. Log in to Redmine as administrator

2. Go to Administration → Settings → API

3. Check "Enable REST web service"

4. Click Save

4.2 Configure Redmine Basic Data (Administrator)

Before using MCP tools, you need to configure Redmine's basic data:

Configure Roles and Permissions

1. Go to Administration → Roles and permissions

2. Create or edit roles (e.g.: Developer, Tester, Project Manager)

3. Assign appropriate permissions to roles (recommend at least: View issues, Add issues, Edit issues)

Configure Trackers

1. Go to Administration → Trackers

2. Create tracker types (e.g.: Bug, Feature, Support)

3. Set default status and workflow for each tracker

Configure Issue Statuses

1. Go to Administration → Issue statuses

2. Create statuses (e.g.: New, In Progress, Resolved, Closed, Rejected)

3. Set status attributes (whether it's a closed status, etc.)

Configure Workflow

1. Go to Administration → Workflow

2. Set allowed status transitions for each role and tracker combination

3. Ensure basic status transition paths (New → In Progress → Resolved → Closed)

Create Projects

1. Go to Projects → New project

2. Set project name, identifier, description

3. Select enabled modules (at least enable "Issue tracking")

4. Assign members and set roles

4.3 Get API Key

1. Log in to your Redmine system (can be administrator or regular user)

2. Go to My account → API access key

3. Click Show or Reset to get the API key

4. Copy the key to REDMINE_API_KEY in the .env file

⚠️ Important Notes:

• If you can't find the API key option, please ensure step 4.1 (Enable REST API) is completed

• Complete basic setup before you can properly create and manage issues

📚 Detailed Setup Guide: For complete Redmine setup steps, please refer to Redmine Complete Setup Guide

🔗 Claude Code Integration

Install to Claude Code

Verify Installation

🌐 SSE Mode & Docker Deployment

Transport Modes

Redmine MCP supports two transport modes:

Running in SSE Mode

Quick Start (Development)

Global Installation

Using .env File

Create a .env file in your working directory:

Note: uv run automatically loads .env from the project directory. Global installation requires explicit environment variables or running from the directory containing .env.

Docker Deployment

Quick Start with Docker

Using Docker Compose

Docker Compose with .env file (Recommended)

1. Create .env file:

2. Update docker-compose.yml to use environment variables:

3. Start the service:

Connecting Claude Code to SSE Server

Once the SSE server is running, configure Claude Code to connect:

Or manually edit ~/.claude.json:

Note: Environment variables (REDMINE_DOMAIN, REDMINE_API_KEY) are configured on the SSE server side, not in Claude Code.

🔄 Updating/Reinstalling MCP

If you need to update to the latest version of the MCP server or reinstall it:

Quick Update (Recommended)

Full Reinstallation

If quick update doesn't work, follow these steps:

1. Remove Previous Installation

2. Install Latest Version

3. Re-register with Claude Code

4. Verify Updated Installation

Troubleshooting Update Issues

Problem: Old version still running after update

• This usually happens when PATH has multiple redmine-mcp executables

• Solution: Use full path in Claude Code MCP config

Problem: "Failed to reconnect to redmine" after update

• Restart Claude Code completely (close and reopen)

• Or use /mcp command and select restart for redmine server

Important Notes:

• Always restart Claude Code after updating MCP server

• Use --force --reinstall flags to ensure clean installation

• Check tool count in /mcp to verify update (current: 26 tools)

🛠️ Available MCP Tools (26 tools)

Basic Tools

Issue Operations

Journal Tools

Attachment Tools ✨ New

Query Tools

User Tools

💡 Usage Examples

Using in Claude Code

🧪 Testing

Run Test Suite

Docker Environment Testing

If you want to test in a local Docker environment:

📁 Project Structure

🤝 Contributing

1. Fork this project

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add some amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

📄 License

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

📦 Changelog

See CHANGELOG.md for version history and release notes.

🔗 Related Links

• Model Context Protocol

• Claude Code

• Redmine

• FastMCP

If you have any questions or suggestions, feel free to open an Issue or contact the project maintainers.