Redmine MCP Server (Read-Only)

A local MCP server for Claude Code, Claude Desktop and Codex. Use it to read Redmine issues, analyze attached logs and screenshots, and compare issue requirements with your code or pull requests.

The server only reads from Redmine: it cannot create, edit or delete issues.

1. Install

You need Node.js 24.15+ in the 24.x line, or Node.js 26+, and a Redmine account with REST API access.

node -v
npm install -g @martin4455/redmine-mcp-ro@latest

2. Configure

Local configuration is the default. Run the configurator in your project directory:

cd "/absolute/path/to/project"
redmine-mcp configure
# Equivalent explicit selection:
redmine-mcp configure --local

To configure a Redmine connection shared across your folders instead:

redmine-mcp configure --global
redmine-mcp status --global

Global metadata lives at ~/.config/redmine-mcp/.redmine-mcp for your OS account. The configurator creates this directory when needed. Add --global when starting the server to use it. Local mode never falls back to global configuration. Each scope can have its own servers and profiles; --profile <name> selects a profile within that scope. For example, configure --global --profile work for your usual server and --local --profile customer inside a specific project. --global cannot be combined with --local or --config-dir.

Enter your Redmine URL (for example, https://redmine.example.com) and API key. HTTPS is required for remote servers. HTTP is accepted only for literal loopback addresses (127.0.0.0/8 or [::1]), such as a local test instance at http://127.0.0.1:8080; HTTP hostnames, including localhost, are rejected. Find the key under My account in Redmine, or Profile > Edit profile > API key in Easy Redmine. Accept the optional connection test to check that they work.

The URL and token are stored in your system credential store: macOS Keychain, Windows Credential Manager or Linux Secret Service (such as GNOME Keyring). The selected .redmine-mcp file stores a reference, not the token. Both scopes use the same system credential store and keep their profile references independent.

3. Connect your client

Choose the registration that matches the Redmine configuration you created.

Local credentials (default):

From the same project directory, run the command for your client.

Claude Code:

claude mcp add redmine-local -- npx -y @martin4455/redmine-mcp-ro@latest --config-dir .

Start Claude Code from this directory so . selects your local configuration. For Windows launch problems, see launcher troubleshooting.

Codex CLI:

Replace the quoted path with the directory you configured above.

codex mcp add redmine-local -- npx -y @martin4455/redmine-mcp-ro@latest --config-dir "/absolute/path/to/project"

Codex saves this registration in your user settings, and the server always uses the specified project's credentials. To limit the registration to that project, use the project configuration example.

Global credentials (all folders):

After redmine-mcp configure --global, register the server from any directory. Use --global as the server argument and omit --config-dir.

Claude Code:

claude mcp add --scope user redmine-global -- npx -y @martin4455/redmine-mcp-ro@latest --global

Codex CLI:

codex mcp add redmine-global -- npx -y @martin4455/redmine-mcp-ro@latest --global

These registrations are available across your folders. Claude Code's --scope user controls where its registration is available; the final --global selects the Redmine credentials. The server's --global belongs after -- and cannot be combined with --config-dir.

To select a specific global profile, append --profile work. Client registration scope and Redmine configuration scope are separate; see CONFIG.md.

Claude Desktop: follow the Desktop setup.

Start or restart your client. In Claude Code or Codex CLI, use /mcp to check the server's status. The first launch may take a moment to download the package.

4. Try it

Ask your assistant:

Use the Redmine MCP server to check whether you can access my Redmine account.

To find issues that need your attention:

Find issues assigned to me that are waiting for my response. Limit the search to the last two months.

Then give it an issue to investigate:

Read Redmine issue 12345, including comments, logs and screenshots. Compare them with the code in this project, diagnose the problem and propose a fix.

You can also ask it to review a pull request against the requirements in an issue.

To save attachments as local files, enable attachment downloads. Issue-wide downloads default to at most 50 attachments, 100 MiB total and two minutes per operation. A limit stops the batch with an error; completed files are retained and the current incomplete file is removed. For profiles, upgrades and troubleshooting, see the configuration guide.

MIT license. Source | Report an issue.