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: Username/password or API key
• 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

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

Variable	Required	Default	Description
REDMINE_URL	Yes	–	Base URL of your Redmine instance
REDMINE_API_KEY	Yes*	–	API key for authentication (or provide username/password)
REDMINE_USERNAME	Yes*	–	Username for basic auth (use with password when not using API key)
REDMINE_PASSWORD	Yes*	–	Password for basic auth
SERVER_HOST	No	0.0.0.0	Host/IP the MCP server binds to
SERVER_PORT	No	8000	Port the MCP server listens on
PUBLIC_HOST	No	localhost	Hostname used when generating download URLs
PUBLIC_PORT	No	8000	Public port used for download URLs
ATTACHMENTS_DIR	No	./attachments	Directory for downloaded attachments
AUTO_CLEANUP_ENABLED	No	true	Toggle automatic cleanup of expired attachments
CLEANUP_INTERVAL_MINUTES	No	10	Interval for cleanup task
ATTACHMENT_EXPIRES_MINUTES	No	60	Expiry window for generated download URLs

* Either REDMINE_API_KEY or the combination of REDMINE_USERNAME and REDMINE_PASSWORD must be provided for authentication. API key authentication is recommended for security.

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.

VS Code has built-in MCP support via GitHub Copilot (requires VS Code 1.102+).

Using CLI (Quickest):

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

Using Command Palette:

1. Open Command Palette (Cmd/Ctrl+Shift+P)
2. Run MCP: Open User Configuration (for global) or MCP: Open Workspace Folder Configuration (for project-specific)
3. Add the configuration:

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

4. Save the file. VS Code will automatically load the MCP server.

Manual Configuration: Create .vscode/mcp.json in your workspace (or mcp.json in your user profile directory):

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

Add to Claude Code using the CLI command:

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

Or configure manually in your Claude Code settings file (~/.claude.json):

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

Add to Codex CLI using the command:

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

Or configure manually in ~/.codex/config.toml:

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

Note: Codex CLI primarily supports stdio-based MCP servers. The above uses mcp-client-http as a bridge for HTTP transport.

Kiro primarily supports stdio-based MCP servers. For HTTP servers, use an HTTP-to-stdio bridge:

1. Create or edit .kiro/settings/mcp.json in your workspace:

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

2. Save the file and restart Kiro. The Redmine tools will appear in the MCP panel.

Note: Direct HTTP transport support in Kiro is limited. The above configuration uses mcp-client-http as a bridge to connect to HTTP MCP servers.

Most MCP clients use a standard configuration format. For HTTP servers:

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

For clients that require a command-based approach with HTTP bridge:

{
  "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 10 tools for interacting with Redmine. For detailed documentation, see Tool Reference.

• Project Management (2 tools)

  • list_redmine_projects - List all accessible projects
  • summarize_project_status - Get comprehensive project status summary

• Issue Operations (6 tools)

  • get_redmine_issue - Retrieve detailed issue information
  • list_my_redmine_issues - List issues assigned to you (with pagination)
  • search_redmine_issues - Search issues by text query
  • create_redmine_issue - Create new issues
  • update_redmine_issue - Update existing issues

• 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