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.
- In Redmineflux, go to Administration → Users → New user and create a user such as
mcp-bot. - Give it the Reporter role on any one project.
- Log in as
mcp-botonce, open My account, and click API access key → Show. - 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
- Copy
redmineflux-mcp.zipto your server and unzip it:unzip redmineflux-mcp.zip cd redmineflux-mcp - 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.
- Log in to Redmineflux.
- Click your username in the top-right corner and select My account.
- In the API access key section on the right, click Show.
- 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.comand your key isa1b2c3d4e5:
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)
- Open the config file:
macOS:~/Library/Application Support/Claude/claude_desktop_config.json
Windows:%APPDATA%\Claude\claude_desktop_config.json - 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>" ] } } } - Close Claude Desktop completely and open it again.
Note:
--allow-httpis needed only when your MCP Server address starts withhttp://. Remove it if you serve the MCP Server overhttps://.
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 plainhttp://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.