by jztan
Provides a production‑ready Model Context Protocol server that exposes Redmine data and operations to AI assistants, with built‑in security, pagination, read‑only mode, and Docker support.
A server that integrates Redmine project‑management systems with Model Context Protocol tools, enabling AI agents to query, create, update, and manage Redmine resources such as issues, projects, time entries, wiki pages, files, and plugin data.
pip install redmine-mcp-server (or use the Docker image)..env file containing REDMINE_URL and authentication credentials (API key, username/password, or OAuth settings). Optional variables control read‑only mode, SSL verification, attachment handling, and plugin activation.redmine-mcp-server (or python -m redmine_mcp_server.main). The server listens on http://localhost:8000 with the MCP endpoint at /mcp.list_redmine_projects, create_redmine_issue, get_redmine_attachment) from your AI workflows.REDMINE_MCP_READ_ONLY) for safe production use.Q: Do I need to run the server on the same machine as Redmine? A: No. The server only needs network access to the Redmine API endpoint; it can run anywhere reachable by your AI agents.
Q: Which authentication method should I choose? A: API key is simplest for single‑user deployments. Use OAuth2 when multiple users need separate permissions.
Q: How do I enable plugin‑specific tools?
A: Set the corresponding environment variable (e.g., REDMINE_CRM_ENABLED=true) and ensure the plugin is installed on the Redmine instance.
Q: Can I restrict the server to read‑only operations?
A: Yes, set REDMINE_MCP_READ_ONLY=true in the .env file.
Q: What is the recommended way to deploy in production?
A: Build and run the Docker image, supply a secure .env file, and enable TLS termination at the front‑end proxy. Use the provided deploy.sh script for a streamlined setup.
Q: How are large attachments handled?
A: Attachments are downloaded to a configurable directory, capped at 200 MB per file, and served via temporary UUID URLs that expire based on ATTACHMENT_EXPIRES_MINUTES.
Q: Where can I find the full list of tools?
A: See the Tool Reference document (docs/tool-reference.md) and the tools/list endpoint of the running 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
REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true): Issues, projects, time tracking, wiki, Gantt, file operations, membership management, products, contacts (CRM), DMSF documents, and moreREDMINE_MCP_READ_ONLY environment variablepip install redmine-mcp-server
.env file with your Redmine credentials (see Installation for template)redmine-mcp-server
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}.
# 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}.
| 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) |
REDMINE_INTROSPECT_CLIENT_ID |
Yes‡ | – | Doorkeeper OAuth client ID used by the MCP server to introspect Bearer tokens (RFC 7662). Register a confidential OAuth app in Redmine with protected_resource? permission — see docs/oauth-setup.md Step 2. |
REDMINE_INTROSPECT_CLIENT_SECRET |
Yes‡ | – | Secret for the introspection client |
HEALTH_INTROSPECTION_TTL_SECONDS |
No | 30 |
TTL (seconds) for the /health Doorkeeper introspection probe cache. Set to 0 to disable caching. |
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:
default_value, orREDMINE_REQUIRED_CUSTOM_FIELD_DEFAULTSExample:
REDMINE_AUTOFILL_REQUIRED_CUSTOM_FIELDS=true
REDMINE_REQUIRED_CUSTOM_FIELD_DEFAULTS='{"Required Field A":"Value A","Required Field B":"Value B"}'
Configure SSL certificate handling for Redmine servers with self-signed certificates or internal CA infrastructure.
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
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).
⚠️ 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.
The server supports two authentication modes, selected via REDMINE_AUTH_MODE.
Backward compatibility:
REDMINE_AUTH_MODEdefaults tolegacy, so all existing deployments continue to work without any configuration changes. OAuth2 support is purely additive — nothing breaks if you never set the variable.
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
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. Since v2.1, the server validates the token against Doorkeeper's RFC 7662 introspection endpoint (POST /oauth/introspect) on Redmine before forwarding it. This enables multi-user deployments where each user authenticates with their own Redmine account, with the token's scopes available to the server (unlocking future per-tool scope enforcement).
REDMINE_AUTH_MODE=oauth
REDMINE_URL=https://redmine.example.com
REDMINE_MCP_BASE_URL=https://redmine-mcp.example.com # public URL of this server
# Introspection client (register a confidential OAuth app in Redmine; see docs/oauth-setup.md)
REDMINE_INTROSPECT_CLIENT_ID=...
REDMINE_INTROSPECT_CLIENT_SECRET=...
In OAuth mode the server also exposes OAuth2 discovery and token management endpoints:
| Endpoint | Standard | Purpose |
|---|---|---|
/.well-known/oauth-protected-resource/mcp |
RFC 9728 §3.1 | Tells clients where to find the authorization server (mounted by FastMCP RemoteAuthProvider) |
/.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:
Authorization: Bearer <token> on every MCP requestFor step-by-step setup instructions, see the OAuth2 Setup Guide.
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:
Cmd/Ctrl+Shift+P)MCP: Open User Configuration (for global) or MCP: Open Workspace Folder Configuration (for project-specific){
"servers": {
"redmine": {
"type": "http",
"url": "http://127.0.0.1:8000/mcp"
}
}
}
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"
}
}
}
Claude Desktop's config file supports stdio transport only. Use FastMCP's proxy via uv to bridge to this HTTP server.
Setup:
{
"mcpServers": {
"redmine": {
"command": "uv",
"args": [
"run",
"--with", "fastmcp",
"fastmcp",
"run",
"http://127.0.0.1:8000/mcp"
]
}
}
}
Config file locations:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonNote: The Redmine MCP server must be running before starting Claude Desktop.
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:
.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
}
}
}
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"]
}
}
}
# Test connection by checking health endpoint
curl http://localhost:8000/health
This MCP server provides 45 tools for interacting with Redmine (plus 1 operator tool exposed by REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true, and 5 plugin-gated tools that opt in via env vars, for a maximum of 46 when all enabled). For detailed documentation, see Tool Reference.
These tools require only a Redmine instance and credentials — no extra plugins or feature flags.
Project Management (9 tools)
list_redmine_projects - List all accessible projectslist_project_issue_custom_fields - List issue custom fields configured for a projectlist_redmine_versions - List versions/milestones for a projectmanage_redmine_version - Create, update, or delete a version/milestonelist_project_members - List members and roles of a projectsummarize_project_status - Get comprehensive project status summarylist_redmine_roles - List all roles defined in the Redmine instance (for discovering valid role_ids)get_project_modules - Retrieve the enabled modules for a projectmanage_project_member - Add, update, or remove a project membershipIssue Operations (13 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 querycreate_redmine_issue - Create new issuesupdate_redmine_issue - Update existing issuesdelete_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 overrideslist_subtasks - List subtasks (child issues) of a given parentget_private_notes - Retrieve private notes on an issuemanage_issue_relation - List, create, or delete issue relationsmanage_issue_watcher - Add or remove a watcher on an issuemanage_issue_note - Edit a journal note's text or toggle its privacymanage_issue_category - List, create, update, or delete issue categoriesget_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 rangemanage_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 entriesimport_time_entries - Bulk import time entries via sequential API calls with per-entry error reportingDiscovery / 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 flaglist_redmine_issue_priorities - List all priority levelslist_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 pagesFile Operations (4 tools)
list_files - List files uploaded to a project's Files sectionupload_file - Upload a new file (base64 content) to a project, optionally tied to a versiondelete_file - Delete a file from a projectget_redmine_attachment - Download an attachment (works in both HTTP and stdio mode)Gantt (1 tool)
get_gantt_chart - Retrieve project timeline data: issues with dates, dependencies, and milestonesMeta (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.These tools require a corresponding Redmine plugin installed on the server and the matching environment variable set to true on the MCP server. They stay completely hidden from tools/list when their flag is unset.
Checklists (2 tools) — set REDMINE_CHECKLISTS_ENABLED=true; requires the RedmineUP Checklists Pro plugin
get_checklist - Retrieve all checklist items for an issueupdate_checklist_item - Update a checklist item's text, done state, or positionProducts (1 tool) — set REDMINE_PRODUCTS_ENABLED=true; requires the RedmineUP Products plugin
manage_product - List, get, create, or update productsContacts (CRM) (1 tool) — set REDMINE_CRM_ENABLED=true; requires the RedmineUP CRM plugin
manage_contact - List, get, create, update, delete, or assign/remove project association for contactsDocuments (DMSF) (1 tool) — set REDMINE_DMSF_ENABLED=true; requires the redmine_dmsf plugin
manage_document - List, get, create (upload), or update (new revision) DMSF documentsHidden from tools/list by default. Set REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true to register them on the MCP surface. The underlying background tasks run regardless of this flag — exposing them only adds the option to drive them through MCP.
cleanup_attachment_files - Manually trigger cleanup of expired attachment files (the background cleanup task runs automatically regardless)# 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 automated deployment script:
chmod +x deploy.sh
./deploy.sh
If you run into any issues, checkout our troubleshooting guide.
Contributions are welcome! Please see our contributing guide for details.
This project is licensed under the MIT License - see the LICENSE file for details.
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
A Model Context Protocol server for Git repository interaction and automation.
by zed-industries
A high‑performance, multiplayer code editor designed for speed and collaboration.
by modelcontextprotocol
Model Context Protocol Servers
by modelcontextprotocol
A Model Context Protocol server that provides time and timezone conversion capabilities.
by cline
An autonomous coding assistant that can create and edit files, execute terminal commands, and interact with a browser directly from your IDE, operating step‑by‑step with explicit user permission.
by upstash
Provides up-to-date, version‑specific library documentation and code examples directly inside LLM prompts, eliminating outdated information and hallucinated APIs.
by daytonaio
Provides a secure, elastic infrastructure that creates isolated sandboxes for running AI‑generated code with sub‑90 ms startup, unlimited persistence, and OCI/Docker compatibility.
by continuedev
Enables faster shipping of code by integrating continuous AI agents across IDEs, terminals, and CI pipelines, offering chat, edit, autocomplete, and customizable agent workflows.
by github
Connects AI tools directly to GitHub, enabling natural‑language interactions for repository browsing, issue and pull‑request management, CI/CD monitoring, code‑security analysis, and team collaboration.