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

Tool reference | Changelog | Contributing | Troubleshooting

Features

• Redmine Integration: List projects, view/create/update issues, download attachments
• HTTP File Serving: Secure file access via UUID-based URLs with automatic expiry
• MCP Compliant: Full Model Context Protocol support with FastMCP and streamable HTTP transport
• Flexible Authentication: API key, username/password, or OAuth2 per-user tokens
• File Management: Automatic cleanup of expired files with storage statistics
• Docker Ready: Complete containerization support
• Pagination Support: Efficiently handle large issue lists with configurable limits
• Read-Only Mode: Restrict to read-only operations via REDMINE_MCP_READ_ONLY environment variable
• Prompt Injection Protection: User-controlled content wrapped in boundary tags for safe LLM consumption

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

REDMINE_AUTOFILL_REQUIRED_CUSTOM_FIELDS=true
REDMINE_REQUIRED_CUSTOM_FIELD_DEFAULTS='{"Required Field A":"Value A","Required Field B":"Value B"}'

SSL Certificate Configuration

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

# In .env file
REDMINE_URL=https://redmine.company.com
REDMINE_API_KEY=your_api_key
REDMINE_SSL_CERT=/path/to/ca-certificate.crt

# In .env file
REDMINE_URL=https://secure.redmine.com
REDMINE_API_KEY=your_api_key
REDMINE_SSL_CERT=/path/to/ca-bundle.pem
REDMINE_SSL_CLIENT_CERT=/path/to/cert.pem,/path/to/key.pem

# In .env file
REDMINE_SSL_VERIFY=false

For SSL troubleshooting, see the Troubleshooting Guide.

Authentication

The server supports two authentication modes, selected via REDMINE_AUTH_MODE.

Backward compatibility: REDMINE_AUTH_MODE defaults to legacy, so all existing deployments continue to work without any configuration changes. OAuth2 support is purely additive — nothing breaks if you never set the variable.

Legacy mode (default)

Uses a single shared credential — either an API key or a username/password pair — 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

OAuth2 mode

Requires Redmine 6.1 or newer. OAuth2 support (via the Doorkeeper gem) was introduced in Redmine 6.1.

Each MCP request carries its own Authorization: Bearer <token> header. The server validates the token against GET /users/current.json on Redmine before forwarding it. This enables multi-user deployments where each user authenticates with their own Redmine account.

REDMINE_AUTH_MODE=oauth
REDMINE_URL=https://redmine.example.com
REDMINE_MCP_BASE_URL=https://redmine-mcp.example.com   # public URL of this server

In OAuth mode the server also exposes OAuth2 discovery and token management endpoints:

Redmine uses the Doorkeeper gem for OAuth2 but does not serve the RFC 8414 discovery document itself. This server serves it on Redmine's behalf, pointing to Redmine's real /oauth/authorize, /oauth/token, and /oauth/revoke endpoints.

Prerequisites for OAuth mode:

• An OAuth application registered in Redmine admin → Applications with the callback URL of your client
• A client that handles the authorization code flow, stores the resulting token per user, and sends it as Authorization: Bearer <token> on every MCP request
• No Dynamic Client Registration (DCR) is required — register the application manually in Redmine admin

For step-by-step setup instructions, see the OAuth2 Setup Guide.

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.

code --add-mcp '{"name":"redmine","type":"http","url":"http://127.0.0.1:8000/mcp"}'

{
  "servers": {
    "redmine": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

claude mcp add --transport http redmine http://127.0.0.1:8000/mcp

{
  "mcpServers": {
    "redmine": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

{
  "mcpServers": {
    "redmine": {
      "command": "uv",
      "args": [
        "run",
        "--with", "fastmcp",
        "fastmcp",
        "run",
        "http://127.0.0.1:8000/mcp"
      ]
    }
  }
}

codex mcp add redmine -- npx -y mcp-client-http http://127.0.0.1:8000/mcp

[mcp_servers.redmine]
command = "npx"
args = ["-y", "mcp-client-http", "http://127.0.0.1:8000/mcp"]

{
  "mcpServers": {
    "redmine": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "mcp-client-http", "http://127.0.0.1:8000/mcp"]
    }
  }
}

Testing Your Setup

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

Available Tools

This MCP server provides 21 tools for interacting with Redmine. For detailed documentation, see Tool Reference.

• Project Management (5 tools)

  • list_redmine_projects - List all accessible projects
  • list_project_issue_custom_fields - List issue custom fields configured for a project
  • list_redmine_versions - List versions/milestones for a project
  • list_project_members - List members and roles of a project
  • summarize_project_status - Get comprehensive project status summary

• Issue Operations (5 tools)

  • get_redmine_issue - Retrieve detailed issue information (supports journal pagination, watchers, relations, children)
  • list_redmine_issues - List issues with flexible filtering (project, status, assignee, etc.)
  • search_redmine_issues - Search issues by text query
  • create_redmine_issue - Create new issues
  • update_redmine_issue - Update existing issues
  • Note: get_redmine_issue can include custom_fields and update_redmine_issue can update custom fields by name (for example {"size": "S"}).

• Time Tracking (4 tools)

  • list_time_entries - List time entries with filtering by project, issue, user, and date range
  • create_time_entry - Log time against projects or issues
  • update_time_entry - Modify existing time entries
  • list_time_entry_activities - Discover available activity types for time entries

• Search & Wiki (5 tools)

  • search_entire_redmine - Global search across issues and wiki pages (Redmine 3.3.0+)
  • get_redmine_wiki_page - Retrieve wiki page content
  • create_redmine_wiki_page - Create new wiki pages
  • update_redmine_wiki_page - Update existing wiki pages
  • delete_redmine_wiki_page - Delete wiki pages

• File Operations (2 tools)

  • get_redmine_attachment_download_url - Get secure download URLs for attachments
  • cleanup_attachment_files - Clean up expired attachment files

Docker Deployment

Quick Start with Docker

# Configure environment
cp .env.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

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.

License

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

Additional Resources

• Tool Reference - Complete tool documentation
• Troubleshooting Guide - Common issues and solutions
• Contributing Guide - Development setup and guidelines
• Changelog - Detailed version history
• 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