Redmine MCP服务器

Prerequisites

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

Installation

Install from PyPI (Recommended)

```bash

Install the package

pip install redmine-mcp-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:

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.

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

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

<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>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 (5, 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 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 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) (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 contacts

• 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 ```

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.