mcp-redmine

A Model Context Protocol server that connects Claude (Desktop or Code) — or any other MCP client — to a Redmine instance through its REST API.

It exposes 73 tools covering, in practice, the entire stable Redmine REST API: issues, relations, projects, memberships, versions, categories, users, groups, roles, wiki, time tracking, attachments, project files, news, and search. Point your agent at a Redmine project and let it read and manage issues, log time, edit wiki pages, and administer users — all through natural conversation.

Features

• Full read/write coverage of issues, including bulk updates, relations, watchers, and comments.

• Project administration: create/update/archive projects, manage members, versions, and categories.

• User and group administration, with deliberately no "delete user" or "delete project" tool — see Security.

• Wiki, including nested pages and file attachments.

• Time tracking, attachments, project files, news, and full-text search.

• Readable errors: every failure comes back as a clear sentence pulled from Redmine's own validation response, not a raw stack trace.

• Nothing to run: a single Python process talking stdio to your MCP client — no database, no server to host, no Docker required.

Related MCP server: redmine-mcp

Prerequisites

• Python 3.10+

• A Redmine instance with the REST API enabled:

  1. In Redmine, go to Administration → Settings → API and enable "Enable REST web service" (if not already on).

  2. Go to My account → API access key and copy the value.

Installation

With uv (recommended)

uv tool install mcp-redmine

With pip

pip install mcp-redmine

From source

git clone https://github.com/alsimoes/mcp-redmine.git
cd mcp-redmine
python3 -m venv venv
source venv/bin/activate        # Linux/Mac
# venv\Scripts\activate         # Windows

pip install -e .

Configuration

The server reads its configuration from two environment variables:

Claude Desktop

Edit (or create) the Claude Desktop configuration file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "redmine": {
      "command": "mcp-redmine",
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

If you installed from source instead of via uv tool install / pip install, point command at the interpreter in your virtual environment and pass the script as an argument:

{
  "mcpServers": {
    "redmine": {
      "command": "/full/path/to/mcp-redmine/venv/bin/python",
      "args": ["-m", "mcp_redmine"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop afterwards. The tools icon (🔨) should show the Redmine tools as available.

Claude Code

claude mcp add redmine \
  --env REDMINE_URL=https://redmine.example.com \
  --env REDMINE_API_KEY=your_api_key_here \
  -- mcp-redmine

Confirm with:

claude mcp list

Other MCP clients

Any client that can launch a local process and speak MCP over stdio works the same way: run mcp-redmine (or python -m mcp_redmine) with REDMINE_URL and REDMINE_API_KEY set in its environment.

Run locally (optional)

Useful for a quick sanity check before wiring the server into a client:

cp .env.example .env   # then edit .env with your values
export $(grep -v '^#' .env | xargs)   # or use a tool like direnv
mcp-redmine

If there's no connection error, the server is ready — it waits for MCP messages on stdin/stdout, so seeing nothing happen in the terminal is normal. Press Ctrl+C to stop it.

Usage examples

Once configured, just talk to the agent:

• "List the open issues assigned to me in the Website project."

• "Create a bug in Website titled 'Login button unresponsive on mobile', priority high."

• "Move issues #101, #104, and #110 to In Progress and assign them to Alice."

• "Log 3.5 hours on issue #204 for today, activity Development."

• "What's on the wiki page 'Deployment' for the Infra project?"

• "Search for 'timeout' across all projects."

Available tools

73 tools, grouped by resource. The full reference — signatures, parameters, return shape, and the caveats that matter (like how precedes reschedules issues, or that list_custom_fields requires an administrator) — lives in docs/TOOLS.md.

API coverage

The two omissions are deliberate. delete_project and delete_user are irreversible and take other people's content down with them — issues, time entries, wiki pages, authorship. archive_project and update_user with status=3 cover the real use case reversibly. Deleting for real remains a web UI operation, where confirmation is explicit and human. See SECURITY.md for the full reasoning.

Trackers, issue statuses, priorities, and roles have no write operations in the Redmine API — they're configurable only in Administration. That's not a gap in this server.

Outside the stable REST API, and therefore outside this server's scope: repositories and changesets, wiki page protection, and instance-wide settings screens.

Error messages

Errors are handled centrally: when Redmine rejects a call, the server reads the response body — that's where the real explanation lives, in the errors field — and returns that sentence. Without a useful body, it falls back to the HTTP status with a likely reason:

This applies to every tool, read and write alike.

Troubleshooting

• "REDMINE_URL and REDMINE_API_KEY must be set": the server checks its configuration at startup and exits immediately with this message rather than starting up broken. Check the env block in your MCP client's configuration.

• Every call fails with a network error: confirm the server process can actually reach REDMINE_URL — MCP clients run the server as a local process, so it needs the same network access as your machine, not the browser.

• 401 on every call: the API key is wrong, or "Enable REST web service" is off in Redmine's settings.

• 403 on a specific tool: usually a missing permission on the role of the user who owns the API key. get_role shows exactly which permissions a role has.

• A tool responds 404 that you'd expect to work: a few endpoints (update_journal_note, update_news/delete_news, update_attachment) were added in specific Redmine versions — see docs/TOOLS.md for the minimum version of each.

Security

See SECURITY.md for the full model. In short: an API key grants access equivalent to the user who owns it, so create a dedicated Redmine user with a role scoped to what you want the agent to do, and use that user's key — don't try to limit the agent by editing this server's code.

Contributing

See CONTRIBUTING.md.

License

MIT