Redmine MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to Redmine. It exposes your Redmine instance’s projects, issues, time tracking, wiki pages, and files as MCP tools.

mcp-name: io.github.jztan/redmine-mcp-server

An AI agent triaging a Redmine sprint through redmine-mcp-server. Try the live demo →

Tool reference | Changelog | Contributing | Troubleshooting

Features

• 53 MCP tools on a stock Redmine, 68 with the RedmineUP and DMSF plugins (plus 1 operator tool gated by REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true): Issues, projects, news, time tracking, wiki, Gantt, file operations, membership management, products, contacts and deals (CRM), DMSF documents, Helpdesk email replies and ticket contacts, and more
• Interactive Kanban Board: show_triage_board renders a live, drag-and-drop issue board right in the chat via the MCP Apps extension
• Flexible Authentication: API key, username/password, OAuth2 per-user tokens, or a browser login with each user’s own API key on Redmines without OAuth
• Prompt Injection Protection: User-controlled content wrapped in boundary tags for safe LLM consumption
• Read-Only Mode: Restrict to read-only operations via REDMINE_MCP_READ_ONLY environment variable
• HTTP File Serving: Secure attachment access via UUID-based URLs with automatic expiry
• Pagination Support: Handle large result sets with configurable limits
• MCP Compliant: Built on FastMCP with HTTP transport
• Docker Ready: Dockerfile, docker-compose setup, and prebuilt images on GHCR

Quick Start

1. Install the package

   pip install redmine-mcp-server
   

2. Create a .env file with your Redmine credentials (see Installation for template)
3. Start the server

   redmine-mcp-server
   

4. Add the server to your MCP client using one of the guides in MCP Client Configuration.

Once running, the server listens on http://localhost:8000 with the MCP endpoint at /mcp, health check at /health, and file serving at /files/{file_id}.

Installation

Prerequisites

• Python 3.10+ (for local installation)
• Docker (alternative deployment, uses Python 3.13)
• Access to a Redmine instance

Redmine Compatibility

The integration suite passes in full against Redmine 6.1 and 7.0. Older versions are untested. Individual tools list their own minimum where one is known (global search needs 3.3.0+, issue watchers 2.3.0+, project time-entry activities 3.4.0+), so on an older server those specific tools fail rather than the whole server.

Per-user authentication works on any version: OAuth2 needs Redmine 6.1+ for Doorkeeper, and the other per-user modes do not. See Authentication to pick a mode.

Install from PyPI (Recommended)

# Install the package
pip install redmine-mcp-server

# Create configuration file .env
cat > .env << 'EOF'
# Redmine connection (required)
REDMINE_URL=https://your-redmine-server.com

# Authentication - Use either API key (recommended) or username/password
REDMINE_API_KEY=your_api_key
# OR use username/password:
# REDMINE_USERNAME=your_username
# REDMINE_PASSWORD=your_password

# Server configuration (optional, defaults shown)
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

# Public URL for file serving (optional)
PUBLIC_HOST=localhost
PUBLIC_PORT=8000

# File management (optional)
ATTACHMENTS_DIR=./attachments
AUTO_CLEANUP_ENABLED=true
CLEANUP_INTERVAL_MINUTES=10
ATTACHMENT_EXPIRES_MINUTES=60
EOF

# Edit .env with your actual Redmine settings
nano .env  # or use your preferred editor

# Run the server
redmine-mcp-server
# Or alternatively:
python -m redmine_mcp_server.main

The server runs on http://localhost:8000 with the MCP endpoint at /mcp, health check at /health, and file serving at /files/{file_id}.

Environment Variables Configuration

SSL Certificate Configuration

Configure SSL certificate handling for Redmine servers with self-signed certificates or internal CA infrastructure.

For SSL troubleshooting, see the Troubleshooting Guide.

Authentication

The server supports five authentication modes, selected via REDMINE_AUTH_MODE. It defaults to legacy, so existing deployments keep working with no changes; OAuth2 support is purely additive.

The advanced modes are collapsed below. For full setup, the OAuth2 Setup Guide covers oauth and oauth-proxy, the api-key-login guide covers api-key-login, and the legacy-per-user guide covers legacy-per-user.

Legacy mode (default)

A single shared credential (API key or username/password) configured once in .env. Every request to Redmine uses the same identity.

REDMINE_AUTH_MODE=legacy        # or omit entirely; this is the default
REDMINE_URL=https://redmine.example.com
REDMINE_API_KEY=your_api_key
# OR:
# REDMINE_USERNAME=your_username
# REDMINE_PASSWORD=your_password

MCP Client Configuration

The server exposes an HTTP endpoint at http://127.0.0.1:8000/mcp. Register it with your preferred MCP-compatible agent using the instructions below. A client that starts MCP servers itself can run this one over stdio instead, with no running server and no bridge: see stdio transport.

The examples below assume legacy or oauth mode. In legacy-per-user mode each client must also send an X-Redmine-API-Key header; see legacy-per-user mode above for header-aware configs.

stdio transport

With REDMINE_MCP_TRANSPORT=stdio the client starts the server as its own process and talks to it over stdin/stdout. Nothing listens on a port, and the HTTP bridges above are not needed. This works in legacy mode only, since the other modes authenticate each HTTP request.

Claude Code:

claude mcp add redmine \
  -e REDMINE_URL=https://your-redmine-server.com \
  -e REDMINE_API_KEY=your_api_key \
  -e REDMINE_MCP_TRANSPORT=stdio \
  -e ATTACHMENTS_DIR=/absolute/path/to/redmine-attachments \
  -- uvx redmine-mcp-server

Claude Desktop, Codex CLI, Kiro and other command-based clients:

{
  "mcpServers": {
    "redmine": {
      "command": "uvx",
      "args": ["redmine-mcp-server"],
      "env": {
        "REDMINE_URL": "https://your-redmine-server.com",
        "REDMINE_API_KEY": "your_api_key",
        "REDMINE_MCP_TRANSPORT": "stdio",
        "ATTACHMENTS_DIR": "/absolute/path/to/redmine-attachments"
      }
    }
  }
}

Without an HTTP server there are no URLs to hand out, so get_redmine_attachment returns a local file_path and create_upload_ticket declines; attach local files with file_path instead (allowed folders: ATTACHMENTS_DIR plus REDMINE_MCP_UPLOAD_FILE_ROOTS). Set ATTACHMENTS_DIR to an absolute path: the default ./attachments is relative to the folder the client starts the server in, which is often the project you have open.

Testing Your Setup

# Test connection by checking health endpoint
curl http://localhost:8000/health

Supported Redmine Plugins

The server works against a stock Redmine instance. Six optional plugins add more, shown as eight rows below because CRM’s deals and Helpdesk’s tickets carry their own flags. To use one, install it on your Redmine server and set the matching env var. Skipping a plugin costs you only that plugin’s features.

Plugin tools appear in the client’s tool list only when their env var is set; with the flag off they are not registered on the MCP surface at all.

Agile and Additional Tags add fields to tools you already have, so they register no new tools. The other seven bring their own, which appear in tools/list either way but return a feature-disabled error until you set the flag. Tags also needs the view_issue_tags, create_issue_tags, and edit_issue_tags permissions on the Redmine server.

Tools for a Redmine plugin written in house can be added from a separate package without forking this server; see Extensions.

Available Tools

A deployment can expose a subset of these with REDMINE_MCP_ALLOW_TOOLS; everything else disappears from tools/list and is refused by call_tool.

This MCP server provides 53 core tools for interacting with Redmine, plus 15 plugin tools that are listed only when the matching REDMINE_*_ENABLED flag is set (68 in total), and 1 operator tool exposed by REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true (maximum of 69). A client connected to a vanilla Redmine sees just the 53 core tools. For full documentation of every tool, see the Tool Reference.

Core tools (53, always available): Project Management (10), Issue Operations (13), Time Tracking (4), Discovery / Enumeration (7), Search & Wiki (2), News (4), File Operations (5), Gantt (1), Interactive Apps (6), Meta (1).

Plugin-gated tools (15, listed only when their flag is set): Checklists (3), Products (1), Contacts / CRM (2), Deals / CRM (3), shared CRM notes and saved queries (2, either CRM flag), deal product lines (1, deals plus products), Documents / DMSF (1), Helpdesk (1), Helpdesk tickets (1). Each requires the matching Redmine plugin installed and its env flag set; with the flag off the tools are not registered on the MCP surface.

Operator tools (1, admin-gated): cleanup_attachment_files, registered only when REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true.

Docker Deployment

Quick Start with Docker

# Configure environment
cp .env.docker.example .env.docker
# Edit .env.docker with your Redmine settings

# Run with docker-compose
docker-compose up --build

# Or run directly
docker build -t redmine-mcp-server .
docker run -p 8000:8000 --env-file .env.docker redmine-mcp-server

Use the Published Image

Prebuilt multi-architecture images (linux/amd64, linux/arm64) are published to the GitHub Container Registry on each release, so you can run the server without building it yourself:

docker pull ghcr.io/jztan/redmine-mcp-server:latest
docker run -p 8000:8000 --env-file .env.docker ghcr.io/jztan/redmine-mcp-server:latest

Pin to an exact version (e.g. ghcr.io/jztan/redmine-mcp-server:2.2.0) or track a minor series (e.g. :2.2). Published images are available starting from the next release.

Production Deployment

Use the automated deployment script:

chmod +x deploy.sh
./deploy.sh

Troubleshooting

If you run into any issues, checkout our troubleshooting guide.

Roadmap

See the roadmap for planned features and future development.

Contributing

Contributions are welcome! Please see our contributing guide for details.

Contributors

Thank you to everyone who has helped improve this project through code, reviews, testing, and feature requests:

@sebastianelsner · @mihajlovicjj · @timcomport · @aadnehovda · @Vitexus · @Bricklou · @martindglaser · @LaurensRietveld · @pdostal · @stevehollis-orderflow · @knasiotis · @azelcs · @fionnb · @goizper · @mmahmed · @andilem · @gino8080 · @siva01c · @chesterXalan · @mliebischer

Per-release contributor credits are listed in the Changelog.

Thanks also to RedmineUP for providing evaluation copies of CRM PRO and Helpdesk PRO, which let the CRM and Helpdesk tools be verified against real Pro instances.

License

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

Blog posts

The story behind the releases. Building this server keeps surprising me: full API access that turned out to be a mistake, 69 tools that had to become 43, an OAuth scope bug that only surfaced when a contributor ran the flow against a real Redmine 6 instance. Plenty of the sharpest lessons arrived from other people’s deployments rather than mine. I write about that thinking in The Dispatch. Come along if that’s your kind of thing.

Background, design notes, and postmortems from building this server:

Getting started

• Redmine MCP Server: Give AI Agents Live Project Data: What the server does, why the tool surface is curated rather than a full API mirror, and how to choose a Redmine MCP server
• How I linked a legacy system to a modern AI agent with MCP: The problem that started this project, and the first two read-only tools

Tool design & architecture

• Designing Reliable MCP Servers: 3 Hard Lessons in Agentic Architecture: Why full API access to an agent was a mistake, and what replaced it
• MCP Tool Sprawl: How I Cut 69 Tools to 43 With a Decorator: The v2 consolidation that cut context overhead and sharpened agent tool selection

Production

• MCP File Upload: Why Base64 Tool Arguments Can Corrupt Files: Why a 3 KB PNG silently lost 32 characters when the model retyped its base64, and the side-channel upload with SHA-256 checks that replaced it
• How to Evaluate an MCP Server With an LLM: 17 Bugs Found and Fixed: Driving the server with an agent surfaced 17 problems the test suite missed, including a role_ids=[True] bug that quietly assigned an elevated role
• What It Actually Takes to Ship a Production MCP Server for Redmine: The full journey from prototype to production