Redmine MCP服务器

Prerequisites

• Python 3.10+ (for local installation)
• Docker (alternative deployment, uses Python 3.13)
• Access to a Redmine instance

Redmine Compatibility

The integration suite passes in full against Redmine 6.1 and 7.0. Older versions are untested. Individual tools list their own minimum where one is known (global search needs 3.3.0+, issue watchers 2.3.0+, project time-entry activities 3.4.0+), so on an older server those specific tools fail rather than the whole server.

OAuth2 is the one hard requirement: it needs Redmine 6.1+ for Doorkeeper support. See docs/oauth-setup.md.

Installation

Install from PyPI (Recommended)

```bash

Install the package

pip install redmine-mcp-server

Confidential OAuth app registered in Redmine admin (see setup guide)

REDMINE_INTROSPECT_CLIENT_ID=... REDMINE_INTROSPECT_CLIENT_SECRET=...

You register the OAuth app manually in Redmine admin → **Applications** (no Dynamic Client Registration). Full walkthrough, endpoint reference, and troubleshooting: [OAuth2 Setup Guide](./docs/oauth-setup.md).

</details>

<details>
<summary><strong>OAuthProxy mode</strong> (hosted deployments with client self-registration)</summary>

FastMCP acts as the MCP-facing authorization server: it handles DCR for MCP clients, then redirects users to Redmine as the upstream OAuth provider for consent. Use this when clients (e.g. Claude Desktop, VS Code) expect to register themselves.

Confidential OAuth app registered in Redmine admin (see setup guide)

REDMINE_INTROSPECT_CLIENT_ID=... REDMINE_INTROSPECT_CLIENT_SECRET=... REDMINE_MCP_JWT_SIGNING_KEY=...

The upstream Redmine app must register `${REDMINE_MCP_BASE_URL}/auth/callback` as its redirect URI. Storage, scaling, and credential-reuse notes are in the [OAuth2 Setup Guide](./docs/oauth-setup.md).

</details>

<details>
<summary><strong>legacy-per-user mode</strong> (Redmine older than 6.1)</summary>

For Redmine instances too old for OAuth, each user's MCP client sends its own Redmine API key in an `X-Redmine-API-Key` header. Each request runs as that user's identity with that user's permissions.

**This is an advanced, opt-in mode.** It requires TLS end-to-end and a correctly configured reverse proxy. Read [`docs/legacy-per-user-auth.md`](docs/legacy-per-user-auth.md) for the threat model, firewall guidance, and revocation runbook before enabling it.

**`mcp-remote` (recommended):**

Note the colon with no surrounding spaces in `X-Redmine-API-Key:${RM_KEY}`. This avoids an arg-escaping bug in Cursor and Claude Desktop on Windows.

**VS Code (`mcp.json`):**

Use `.vscode/mcp.json` (workspace file) or the user profile `mcp.json`. The workspace `.mcp.json` silently drops `headers` (see microsoft/vscode#319528), so do not use that file. Pin VS Code 1.102 or newer.

Unsupported: any client that cannot set a custom request header, or that reserves the Authorization header for its own OAuth flow.

</details>

Testing Your Setup

```bash

Docker Deployment

Quick Start with Docker

```bash

Edit .env.docker with your Redmine settings

Run with docker-compose

docker-compose up --build

Production Deployment

Use the automated deployment script:

chmod +x deploy.sh
./deploy.sh

Quick Start

1. Install the package

   pip install redmine-mcp-server
   

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

Create configuration file .env

cat > .env << 'EOF'

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

Environment Variables Configuration

<details> <summary><strong>Environment Variables</strong></summary>

\ Required when REDMINE_AUTH_MODE=legacy-per-user. † 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 or REDMINE_AUTH_MODE=oauth-proxy. § Required when REDMINE_AUTH_MODE=oauth-proxy.* Secret values can also be supplied with Docker/Kubernetes-style file variables: REDMINE_INTROSPECT_CLIENT_SECRET_FILE, REDMINE_MCP_JWT_SIGNING_KEY_FILE, and REDMINE_OAUTH_CLIENT_SECRET_FILE.

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

In practice only the second one can fire. The server reads project custom fields from GET /projects/{id}.json?include=issue_custom_fields, which Redmine renders as id and name only, so it never sees default_value -- see list_project_issue_custom_fields. Set the env map if you want autofill to have anything to work with.

Example:

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

</details>

SSL Certificate Configuration

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

<details> <summary><strong>Self-Signed Certificates</strong></summary>

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

```bash

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`

</details>

<details>
<summary><strong>Mutual TLS (Client Certificates)</strong></summary>

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).

</details>

<details>
<summary><strong>Disable SSL Verification (Development Only)</strong></summary>

⚠️ **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.

</details>

For SSL troubleshooting, see the Troubleshooting 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.

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.

<details> <summary><strong>Visual Studio Code (Native MCP Support)</strong></summary>

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

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

</details>

<details> <summary><strong>Claude Code</strong></summary>

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

</details>

<details> <summary><strong>Claude Desktop (macOS & Windows)</strong></summary>

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

1. Save the file, then fully quit and restart Claude Desktop
2. 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.

</details>

<details> <summary><strong>Cursor</strong></summary>

Cursor talks to HTTP MCP servers directly, with no bridge.

1. Create ~/.cursor/mcp.json (available in every project) or .cursor/mcp.json in your project root (that project only):

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

Note: Cursor identifies a remote server by a bare url and has no type field, unlike the VS Code and Claude Code configs above.

In legacy-per-user mode, add the API key header:

{
  "mcpServers": {
    "redmine": {
      "url": "https://your-host/mcp",
      "headers": { "X-Redmine-API-Key": "<your redmine api key>" }
    }
  }
}

In oauth mode, set REDMINE_OAUTH_DISCOVERY_AS=self on the MCP server. Cursor looks for authorization server metadata at its own canonical well-known location, which the default (redmine) discovery profile does not serve, so the flow stalls without it (#188). See Cursor and self-AS discovery.

</details>

<details> <summary><strong>Codex CLI</strong></summary>

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.

</details>

<details> <summary><strong>Kiro</strong></summary>

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

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.

</details>

<details> <summary><strong>Generic MCP Clients</strong></summary>

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

</details>

Plugin-gated tools (13, opt in via env var)

These tools require a corresponding Redmine plugin installed on the server and the matching environment variable set to true on the MCP server. They are listed in tools/list only when their flag is set; with the flag off they are not registered on the MCP surface (and a direct call still returns a feature-disabled error).

• Checklists (3 tools): set REDMINE_CHECKLISTS_ENABLED=true; requires the RedmineUP Checklists Pro plugin
• get_checklist - Retrieve all checklist items for an issue
• create_checklist_item - Add a new checklist item to an issue
• update_checklist_item - Update a checklist item's text, done state, or position

• Products (1 tool): set REDMINE_PRODUCTS_ENABLED=true; requires the RedmineUP Products plugin
• manage_product - List, get, create, or update products

• Contacts (CRM) (2 tools): set REDMINE_CRM_ENABLED=true; requires the RedmineUP CRM plugin. In OAuth mode the flag also adds the CRM permissions to the advertised scopes, so grant them on the OAuth application and have users re-consent. Set REDMINE_CRM_EDITION=pro on a Pro install to allow the contact list filters the Light build does not register
• manage_contact - List, get, create, update, delete, or assign/remove project association for contacts
• list_contact_tags - Tags in use on contacts, with colors, for the tags filter and tag_list

• Deals (CRM) (3 tools): set REDMINE_DEALS_ENABLED=true; requires the Pro edition of the same CRM plugin, and the deals project module enabled on the project. Deals have their own flag because the Light edition defines none of the deal permissions, so advertising them would break consent for Light deployments
• manage_deal - List, get, create, update, or delete deals
• list_deal_statuses - Deal statuses (admin-only on the plugin side) and a project's deal categories, for use before creating a deal
• manage_deal_category - List, create, rename, or delete a project's deal categories

• CRM notes and saved queries (2 tools, shared): available when either REDMINE_CRM_ENABLED or REDMINE_DEALS_ENABLED is set; each call is gated on the flag matching the note's or query's source
• manage_crm_note - Get, create, update, or delete CRM notes on contacts and deals
• list_crm_queries - Saved contact or deal queries

• Deal product lines (1 tool): needs both REDMINE_DEALS_ENABLED=true and REDMINE_PRODUCTS_ENABLED=true; the endpoint exists only when the Products plugin is installed next to CRM
• add_deal_product - Add a catalogue or free-form product line to a deal

• Documents (DMSF) (1 tool): set REDMINE_DMSF_ENABLED=true; requires the redmine_dmsf plugin
• manage_document - List, get, create (upload), or update (new revision) DMSF documents

Configure environment

cp .env.docker.example .env.docker

Authentication - Use either API key (recommended) or username/password

REDMINE_API_KEY=your_api_key

Test connection by checking health endpoint

curl http://localhost:8000/health ```

Supported Redmine Plugins

The server works against a stock Redmine instance. Six optional plugins add more, shown as seven rows below because CRM's deals carry their own flag. To use one, install it on your Redmine server and set the matching env var. Skipping a plugin costs you only that plugin's features.

Plugin tools appear in the client's tool list only when their env var is set; with the flag off they are not registered on the MCP surface at all.

Agile and Additional Tags add fields to tools you already have, so they register no new tools. The other five bring their own, which appear in tools/list either way but return a feature-disabled error until you set the flag. Tags also needs the view_issue_tags, create_issue_tags, and edit_issue_tags permissions on the Redmine 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}.

[Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./docs/contributing.md) | [Troubleshooting](./docs/troubleshooting.md)

Troubleshooting

If you run into any issues, checkout our troubleshooting guide.