Redmine MCP Server

A Model Context Protocol (MCP) server that integrates with Redmine project management systems. This server provides seamless access to Redmine data through MCP tools, enabling AI assistants to interact with your Redmine instance.

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

• 49 MCP Tools (plus 1 operator tool gated by REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true): Issues, projects, time tracking, wiki, Gantt, file operations, membership management, products, contacts (CRM), DMSF documents, 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, or OAuth2 per-user tokens
• 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: Efficiently handle large result sets with configurable limits
• MCP Compliant: Full Model Context Protocol support with FastMCP and HTTP transport
• Docker Ready: Complete containerization support

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

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 four 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, 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.

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.

Testing Your Setup

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

Available Tools

This MCP server provides 51 tools for interacting with Redmine (plus 1 operator tool exposed by REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true, for a maximum of 52). 6 of the 51 are plugin-gated and activate via env vars. For full documentation of every tool, see the Tool Reference.

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

Plugin-gated tools (6, opt in via env var): Checklists (3), Products (1), Contacts / CRM (1), Documents / DMSF (1). Each requires the matching Redmine plugin installed and its env flag set; they appear in tools/list either way but return a feature-disabled error until enabled.

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.

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 · @aadnehovda · @martindglaser · @Vitexus · @timcomport · @Bricklou · @LaurensRietveld

Per-release contributor credits are listed in the Changelog.

License

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

Additional Resources

• Roadmap - Future development plans
• Blog: How I linked a legacy system to a modern AI agent with MCP - The story behind this project
• Blog: Designing Reliable MCP Servers: 3 Hard Lessons in Agentic Architecture - Lessons learned building this server
• Blog: What It Actually Takes to Ship a Production MCP Server for Redmine - The full journey from prototype to production
• Blog: MCP Tool Sprawl: How I Cut 69 Tools to 43 With a Decorator - The major v2 architecture change that consolidated the tools to cut context overhead and sharpen agent tool selection