redmine-mcp-server 2.0.1

Production-ready MCP server for Redmine with security, pagination, and enterprise features

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

• 44 MCP Tools: Issues, projects, time tracking, wiki, Gantt, file operations, membership management, products, contacts (CRM), DMSF documents, and more
• 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

Environment Variables

Variable	Required	Default	Description
REDMINE_URL	Yes	–	Base URL of your Redmine instance
REDMINE_AUTH_MODE	No	legacy	Authentication mode: legacy or oauth (see Authentication)
REDMINE_API_KEY	Yes†	–	API key (legacy mode only)
REDMINE_USERNAME	Yes†	–	Username for basic auth (legacy mode only)
REDMINE_PASSWORD	Yes†	–	Password for basic auth (legacy mode only)
REDMINE_MCP_BASE_URL	Yes‡	http://localhost:3040	Public base URL of this server, no trailing slash (OAuth mode only)
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
REDMINE_PUBLIC_URL	No	–	Publicly-reachable URL of your Redmine instance. When set, content_url values returned on attachments are rewritten from REDMINE_URL's origin to this one (preserving path/query/fragment and any reverse-proxy subpath). Useful when REDMINE_URL is the internal container hostname unreachable from MCP clients. When unset, the raw URL Redmine echoes back is returned.
ATTACHMENTS_DIR	No	./attachments	Directory for downloaded attachments
ATTACHMENT_MAX_DOWNLOAD_BYTES	No	209715200 (200 MB)	Cap applied to every get_redmine_attachment download regardless of content type. Exceeding the cap aborts the download mid-stream and deletes the partial file.
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
REDMINE_MCP_EXPOSE_ADMIN_TOOLS	No	false	Expose operator/admin tools on the MCP surface. Currently gates cleanup_attachment_files. The background cleanup task runs regardless of this flag.
REDMINE_SSL_VERIFY	No	true	Enable/disable SSL certificate verification
REDMINE_SSL_CERT	No	–	Path to custom CA certificate file
REDMINE_SSL_CLIENT_CERT	No	–	Path to client certificate for mutual TLS
REDMINE_MCP_READ_ONLY	No	false	Block all write operations (create/update/delete) when set to true
REDMINE_AGILE_ENABLED	No	false	Enable RedmineUP Agile plugin support: get_redmine_issue returns story_points, agile_sprint_id, agile_position; update_redmine_issue accepts story_points
REDMINE_CHECKLISTS_ENABLED	No	false	Enable RedmineUP Checklists plugin support: get_checklist, update_checklist_item (requires Checklists Pro plugin)
REDMINE_PRODUCTS_ENABLED	No	false	Enable RedmineUP Products plugin support: manage_product (action=list/get/create/update)
REDMINE_CRM_ENABLED	No	false	Enable RedmineUP CRM plugin support: manage_contact (action=list/get/create/update/delete/assign_to_project/remove_from_project)
REDMINE_DMSF_ENABLED	No	false	Enable DMSF document-management plugin support: manage_document (action=list/get/create/update). Requires redmine_dmsf plugin on the Redmine server.
REDMINE_AUTOFILL_REQUIRED_CUSTOM_FIELDS	No	false	Enable one retry for issue creation by filling missing required custom fields
REDMINE_REQUIRED_CUSTOM_FIELD_DEFAULTS	No	{}	JSON object mapping required custom field names to fallback values used when creating issues
REDMINE_ALLOW_PRIVATE_FETCH_URLS	No	false	Warning: disables all SSRF protection for attachment fetching. Never set to true in production.

† Required when REDMINE_AUTH_MODE=legacy. Either REDMINE_API_KEY or REDMINE_USERNAME+REDMINE_PASSWORD must be set. API key is recommended. ‡ Required when REDMINE_AUTH_MODE=oauth.

When REDMINE_AUTOFILL_REQUIRED_CUSTOM_FIELDS=true, create_redmine_issue retries once on relevant custom-field validation errors (for example <Field Name> cannot be blank or <Field Name> is not included in the list) and fills values only from:

• the Redmine custom field default_value, or
• REDMINE_REQUIRED_CUSTOM_FIELD_DEFAULTS

Example:

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.

Self-Signed Certificates

If your Redmine server uses a self-signed certificate or internal CA:

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

Supported certificate formats: .pem, .crt, .cer

Mutual TLS (Client Certificates)

For environments requiring client certificate authentication:

# 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

Note: Private keys must be unencrypted (Python requests library requirement).

Disable SSL Verification (Development Only)

⚠️ WARNING: Only use in development/testing environments!

# In .env file
REDMINE_SSL_VERIFY=false

Disabling SSL verification makes your connection vulnerable to man-in-the-middle attacks.

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:

Endpoint	Standard	Purpose
/.well-known/oauth-protected-resource	RFC 8707	Tells clients where to find the authorization server
/.well-known/oauth-authorization-server	RFC 8414	Advertises Redmine's Doorkeeper OAuth endpoints
POST /revoke	RFC 7009	Revokes an OAuth2 token (proxies to Redmine's /oauth/revoke)

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.

Visual Studio Code (Native MCP Support)

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"
    }
  }
}

Claude Code

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"
    }
  }
}

Claude Desktop (macOS & Windows)

Claude Desktop's config file supports stdio transport only. Use FastMCP's proxy via uv to bridge to this HTTP server.

Setup:

1. Open Claude Desktop
2. Click the Claude menu (macOS menu bar / Windows title bar) > Settings...
3. Click the Developer tab > Edit Config
4. Add the following configuration:

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

5. Save the file, then fully quit and restart Claude Desktop
6. Look for the tools icon in the input area to verify the connection

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Note: The Redmine MCP server must be running before starting Claude Desktop.

Codex CLI

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

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.

Generic MCP Clients

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 46 tools for interacting with Redmine (plus 1 operator tool exposed by REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true). For detailed documentation, see Tool Reference.

• Project Management (9 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
  • manage_redmine_version - Create, update, or delete a version/milestone
  • list_project_members - List members and roles of a project
  • summarize_project_status - Get comprehensive project status summary
  • list_redmine_roles - List all roles defined in the Redmine instance (for discovering valid role_ids)
  • get_project_modules - Retrieve the enabled modules for a project
  • manage_project_member - Add, update, or remove a project membership

• Issue Operations (12 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
  • delete_redmine_issue - Hard-delete an issue with required confirmation flags and a cascade-impact preview before irreversible deletion.
  • copy_issue - Duplicate an existing issue with optional field overrides
  • list_subtasks - List subtasks (child issues) of a given parent
  • get_private_notes - Retrieve private notes on an issue
  • manage_issue_relation - List, create, or delete issue relations
  • manage_issue_watcher - Add or remove a watcher on an issue
  • manage_issue_note - Edit a journal note's text or toggle its privacy
  • manage_issue_category - List, create, update, or delete issue categories
  • 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
  • manage_time_entry - Create or update a time entry (use user_id to log on behalf of another user)
  • list_time_entry_activities - Discover available activity types for time entries
  • import_time_entries - Bulk import time entries via sequential API calls with per-entry error reporting

• Discovery / Enumeration (6 tools): help LLMs find valid IDs before calling create/update tools

  • list_redmine_trackers - List all trackers (Bug, Feature, Support, etc.)
  • list_redmine_issue_statuses - List all issue statuses with their is_closed flag
  • list_redmine_issue_priorities - List all priority levels
  • list_redmine_users - Filter/list users (admin-only; supports name and group filters)
  • get_current_user - Get the authenticated user's profile (works for non-admins)
  • list_redmine_queries - List saved custom queries (read-only)

• Search & Wiki (2 tools)

  • search_entire_redmine - Global search across issues and wiki pages (Redmine 3.3.0+)
  • manage_redmine_wiki_page - List, get, create, update, delete, or rename wiki pages

• File Operations (4 tools, plus 1 admin-gated)

  • list_files - List files uploaded to a project's Files section
  • upload_file - Upload a new file (base64 content) to a project, optionally tied to a version
  • delete_file - Delete a file from a project
  • get_redmine_attachment - Download an attachment (works in both HTTP and stdio mode)
  • cleanup_attachment_files - Clean up expired attachment files (operator-gated by REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true; the background cleanup task runs automatically regardless)

• Checklists (2 tools, requires REDMINE_CHECKLISTS_ENABLED=true + RedmineUP Checklists Pro plugin)

  • get_checklist - Retrieve all checklist items for an issue
  • update_checklist_item - Update a checklist item's text, done state, or position

• Gantt (1 tool, no plugin required)

  • get_gantt_chart - Retrieve project timeline data: issues with dates, dependencies, and milestones

• Products (1 tool, requires REDMINE_PRODUCTS_ENABLED=true + RedmineUP Products plugin)

  • manage_product - List, get, create, or update products

• Contacts (CRM) (1 tool, requires REDMINE_CRM_ENABLED=true + RedmineUP CRM plugin)

  • manage_contact - List, get, create, update, delete, or assign/remove project association for contacts

• Documents (DMSF) (1 tool, requires REDMINE_DMSF_ENABLED=true + redmine_dmsf plugin)

  • manage_document - List, get, create (upload), or update (new revision) DMSF documents

• Meta (1 tool)

  • get_mcp_server_info - Report server version, auth mode, read-only state, and which plugin-gated tool families are enabled. Use to detect deployment lag before relying on a recently-shipped fix.

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

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

• 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