Our previous licensing terms apply to every order until 31 December 2026, per installation, no user limit, plus 10% Black Friday and year-end discount. See details See details
Support Buy Now
Plugin guide

Redmineflux MCP

Install the self-hosted Redmineflux MCP Server on your own Linux server and connect Claude Code, Claude Desktop or other MCP clients to your Redmine.

Introduction

Redmineflux MCP Server connects AI assistants such as Claude directly to your Redmineflux (Redmine). It uses the open Model Context Protocol (MCP) standard. Your team can then work with Redmineflux in plain language, for example:

  • “What are my critical issues today?”
  • “Log 2 hours on issue #1023 for development work.”
  • “Show the agile board for the Mobile App project.”
  • “Which team members are over-allocated this week?”

This guide is for the self-hosted MCP Server: you install it on your own Linux server. It comes as one ready-to-run program, so you don’t need Docker, Python or any source code.

Using Redmineflux Cloud? Your MCP Server is already hosted for you, so follow the Redmineflux MCP knowledgebase instead.

Using Redmineflux Crux? The MCP Server is part of the Crux bundle. Follow the Redmineflux Crux knowledgebase, which includes this installation.

What You Receive

One file: redmineflux-mcp.zip. It contains:

File What it is
redmineflux-mcp The MCP Server program
Library files and folders Files the program needs. Keep them in the same folder as the program.
install.sh Installs the server as a system service
.env.example The settings template
SETUP.md A short copy of these setup steps

How It Works

Person asks in an AI assistant (Claude Desktop, Claude Code, …)
│
▼
Redmineflux MCP Server     (your server, port 8080)
│  uses the person's own API key
▼
Your Redmineflux
│
▼
The answer goes back to the AI assistant

Every person connects with their own Redmineflux API key, so each person can only see and change what their Redmineflux permissions allow. Many people can share one server.

When the server starts, it detects which Redmineflux plugins are installed and offers tools only for those plugins.

System Requirements

Item Requirement
Server Linux x86_64: CentOS 7 / RHEL 7 or later, or any current Ubuntu or Debian
Tools on the server unzip and systemd (standard on current Linux distributions)
Redmineflux REST API Enabled: Administration → Settings → API → Enable REST web service
Network People’s computers must reach the server on port 8080
Claude Desktop only Node.js 18 or later on each person’s computer

Quick Setup Checklist

# Step Done when
1 Create a bot user in Redmineflux and copy its API key You have the bot’s key
2 Unzip and run sudo ./install.sh The installer finishes
3 Set 2 values in /opt/redmineflux-mcp/.env (3 if people should make changes) The file is saved
4 Start the service The log shows Detected plugins: …
5 Each person connects their AI assistant with their own API key The assistant lists Redmineflux tools
6 Ask “Show me my open issues” You get your own data back

Installation

Step 1 — Create a bot user for the server

The server needs one API key of its own. It uses it only at start-up, to check that it can reach Redmineflux and to detect installed plugins. It never uses it for anyone’s requests.

  1. In Redmineflux, go to Administration → Users → New user and create a user such as mcp-bot.
  2. Give it the Reporter role on any one project.
  3. Log in as mcp-bot once, open My account, and click API access key → Show.
  4. Copy the key.

Tip: Don’t use an administrator’s key here. A low-privilege bot user keeps your Redmineflux safe even if the server’s settings file is ever exposed.

Step 2 — Install

  1. Copy redmineflux-mcp.zip to your server and unzip it:
    unzip redmineflux-mcp.zip
    cd redmineflux-mcp
  2. Run the installer:
    sudo ./install.sh
    It copies the server to /opt/redmineflux-mcp, creates a dedicated service user, creates the settings file and installs the system service.

Step 3 — Configure

Open the settings file:

sudo nano /opt/redmineflux-mcp/.env

Set these values:

Setting Value
REDMINE_URL Your Redmineflux address, for example https://redmine.yourcompany.com
REDMINE_API_KEY The bot user’s key from Step 1
REDMINEFLUX_READ_ONLY true (the default) lets people only read data. Set it to false to let people create, update and delete through their AI assistant.

Leave every other setting as it is.

Step 4 — Start the server

sudo systemctl enable --now redmineflux-mcp
journalctl -u redmineflux-mcp -f

The server is ready when the log shows lines like:

Redmineflux MCP v1.0.0 … Detected plugins: agile, timesheet, workload …
Uvicorn running on http://0.0.0.0:8080

Your MCP Server address is now:

http://<your-server-address>:8080/mcp

Use this address wherever this guide shows <YOUR_MCP_SERVER_URL>.

How To: Get Your Personal API Key

Each person connects with their own key, not the bot’s key.

  1. Log in to Redmineflux.
  2. Click your username in the top-right corner and select My account.
  3. In the API access key section on the right, click Show.
  4. Copy the key.

Important: Treat your API key like a password. Don’t share it, and don’t commit it to version control.

How To: Connect Claude Code (CLI / VS Code)

Run this once. It adds Redmineflux for every project you open:

claude mcp add redmineflux --transport http --scope user <YOUR_MCP_SERVER_URL> --header "X-Redmine-API-Key: <YOUR_API_KEY>"

Worked example: if your server is mcp.yourcompany.com and your key is a1b2c3d4e5:

claude mcp add redmineflux --transport http --scope user http://mcp.yourcompany.com:8080/mcp --header "X-Redmine-API-Key: a1b2c3d4e5"

How To: Connect Claude Desktop (Mac / Windows)

  1. Open the config file:
    macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. Add this entry inside mcpServers:
    {
      "mcpServers": {
        "redmineflux": {
          "command": "npx",
          "args": [
            "mcp-remote@0.1.17",
            "<YOUR_MCP_SERVER_URL>",
            "--transport",
            "http-only",
            "--allow-http",
            "--header",
            "X-Redmine-API-Key: <YOUR_API_KEY>"
          ]
        }
      }
    }
  3. Close Claude Desktop completely and open it again.

Note: --allow-http is needed only when your MCP Server address starts with http://. Remove it if you serve the MCP Server over https://.

How To: Connect Other MCP Clients

Cursor, Windsurf and other MCP clients use the same details:

  • Type: Streamable HTTP
  • URL: <YOUR_MCP_SERVER_URL>
  • Header: X-Redmine-API-Key: <YOUR_API_KEY>

Claude.ai (web): Claude.ai connects from the internet, so it needs your MCP Server on a public https:// address, for example behind your web server or a reverse proxy. Claude Code, Claude Desktop and other desktop clients work with the plain http:// address on your network.

How To: Verify the Connection

Restart your AI client, then ask:

“Show me my Redmine projects”

If you get your project list, the connection works. To see which plugins were detected, ask:

“Show the MCP server version and installed plugins”

Permissions

The MCP Server never gives anyone more access than they have in Redmineflux. Every request runs as the person whose API key is used. To let someone use a feature through their AI assistant, give their Redmineflux role the same permission they would need in Redmineflux itself, under Administration → Roles and permissions.

Changes (create, update, delete, log time) also need REDMINEFLUX_READ_ONLY=false on the server.

Everyday Server Commands

Task Command
Is it running? sudo systemctl status redmineflux-mcp
Live log journalctl -u redmineflux-mcp -f
Restart (after editing .env) sudo systemctl restart redmineflux-mcp
Stop sudo systemctl stop redmineflux-mcp
Version /opt/redmineflux-mcp/redmineflux-mcp --version

Updating

Unzip the new package, run sudo ./install.sh again, then run sudo systemctl restart redmineflux-mcp. Your .env settings are kept.

Troubleshooting

Problem: The server stops right after starting

Cause: A required setting is missing from .env.

Solution: Check that REDMINE_URL and REDMINE_API_KEY are set, and that REDMINEFLUX_TRANSPORT=streamable-http is still in the file. Then restart the service and check the log.

Problem: The log says “API key is invalid (401)” at start-up

Cause: The bot user’s key in .env is wrong, has been reset, or the bot user is locked.

Solution: Copy the bot user’s key again (Step 1), update REDMINE_API_KEY, and restart the service.

Problem: The AI client can’t connect

Cause: The address is wrong, or port 8080 is blocked.

Solution: Check that the address ends in /mcp, that the service is running, and that port 8080 is open in the server’s firewall.

Problem: The AI client connects, but every request fails

Cause: The personal API key in the client’s config is missing or wrong.

Solution: Copy your key again from My account → API access key, update your client’s config, and restart the client completely.

Problem: Tools for a plugin are missing

Cause: The plugin isn’t installed or enabled.

Solution: Check Administration → Plugins and the project’s Settings → Modules. Then restart the MCP Server so that it detects the plugin again.

Problem: Create, update or delete requests are refused

Cause: The server is in read-only mode, which is the default.

Solution: Set REDMINEFLUX_READ_ONLY=false in /opt/redmineflux-mcp/.env and restart the service.

Frequently Asked Questions (FAQs)

Q1: Does the MCP Server need Docker or Python?

No. It is one ready-to-run program for Linux.

Q2: Can many people use one server?

Yes. Each person connects with their own API key and sees only what their own permissions allow.

Q3: Does the MCP Server store my Redmineflux data?

No. It passes each request to Redmineflux and returns the answer. It keeps no copy of your data.

Q4: Is the bot user’s key used for people’s requests?

No. It is used only at start-up, to check the connection and detect plugins.

Q5: Which AI assistants can I use?

Claude Code, Claude Desktop, Claude.ai and any other client that supports MCP over Streamable HTTP, such as Cursor and Windsurf.

Q6: How do I stop people from changing data?

Keep REDMINEFLUX_READ_ONLY=true, which is the default. People can then only read. You can also limit what each person can do through their Redmineflux roles.

Q7: Where do I get help?

Contact the Redmineflux support team at redmineflux.com/contact-us. Include the output of redmineflux-mcp --version and the recent server log from journalctl -u redmineflux-mcp.

Conclusion

With the self-hosted Redmineflux MCP Server, your team can work with Redmineflux from their AI assistant, in plain language. The server runs on your own infrastructure, uses each person’s own permissions, and offers tools for every Redmineflux plugin you have installed.

Need a hand?Write to support@redmineflux.com – we answer within one business day, Monday to Friday.
Contact support