Redmineflux MCP

Introduction #

Redmineflux MCP Server is an AI integration layer that connects your Redmine project management instance directly to AI assistants such as Claude by Anthropic. Using the Model Context Protocol (MCP) standard, it gives AI tools real-time, two-way access to your Redmine data — issues, projects, time entries, checklists, sprints, helpdesk tickets, workload data, and more.

MCP Integration is available on the Pro Plan and above.

Visit redmineflux.com/cloud-redmine-pricing to view plans and upgrade.

Instead of manually searching Redmine, copying data into a chat window, or writing reports by hand, your team can simply ask an AI assistant questions like:

• “What are my critical issues today?”
• “Log 2 hours on issue #1023 for development work.”
• “Show the agile board for the Mobile App project.”
• “Create a sprint named ‘Release 2.1’ with a 2-week duration.”
• “Which team members are over-allocated this week?”

Redmineflux MCP handles the translation between natural language and Redmine API calls automatically — with full permission enforcement, user-friendly error messages, and support for every Redmineflux plugin included in your plan.

What is MCP (Model Context Protocol)? #

Model Context Protocol (MCP) is an open standard developed by Anthropic that allows AI models to securely connect to external tools, data sources, and APIs. Think of it as a universal plug between an AI assistant and any software product.

When an MCP server is connected to an AI client (such as Claude Desktop or Claude.ai), the AI can:

• Read data from the connected system (e.g., list Redmine issues, view project stats)
• Write data back to the system (e.g., create issues, log time, update statuses)
• Execute actions on behalf of the user (e.g., move a card on the agile board, approve a timesheet)

All communication goes through a local or hosted MCP server process. Your Redmine credentials never leave your infrastructure — the AI only receives the formatted data it needs to answer your question.

Supported AI Clients:

Client	Transport	Notes
Claude Desktop (Mac)	stdio	Fully supported
Claude Desktop (Windows)	stdio	Fully supported
Claude.ai Web	SSE (remote)	Requires hosted MCP server
Claude Code (CLI)	stdio	Fully supported
VS Code + Claude extension	stdio	Fully supported
Any MCP-compatible client	stdio / SSE	Fully supported

System Requirements #

Server Requirements #

Component	Minimum Version
Python	3.12 or higher
Redmine	5.0.x, 5.1.x, 6.0.x, 6.1.x
Redmineflux Plan	Pro or Enterprise
Redmineflux Plugins	Installed versions must match plugin API endpoints
Operating System	Linux, macOS, or Windows

AI Client Requirements #

Client	Minimum Version
Claude Desktop	Latest (download from claude.ai)
Claude Code CLI	Latest (npm install -g @anthropic-ai/claude-code)
Claude.ai	Web browser, any modern browser

Network Requirements #

• The MCP server machine must have HTTP/HTTPS access to your Redmine instance
• For local (stdio) mode: the AI client and MCP server run on the same machine
• For hosted (SSE) mode: the MCP server must be reachable via a public URL

How Redmineflux MCP Works #

User Prompt (natural language)
│
▼
AI Assistant (Claude)
│ selects the right tool
▼
Redmineflux MCP Server
│ calls Redmine REST API
▼
Your Redmine Instance
│ returns data
▼
MCP Server formats response
│
▼
AI Assistant presents result to user

Step-by-step flow:

1. User types a request in the AI chat (e.g., “Show open bugs in the Mobile project”)
2. Claude selects the most relevant MCP tool (e.g., redmineflux_core_list_issues)
3. The MCP server sends an authenticated REST API call to your Redmine instance
4. Redmine returns the raw JSON data
5. The MCP server formats it into a readable response
6. Claude presents the formatted result to the user

Plugin detection at startup:

When the MCP server starts, it automatically probes your Redmine instance to detect which Redmineflux plugins are installed. Only tools for detected plugins are registered. If Timesheet Plugin is not installed, timesheet tools are not shown. This prevents confusion from tools that would always return errors.

Installation #

Prerequisite: MCP Integration is available on the Pro Plan and above. Verify your plan at redmineflux.com before proceeding.

Step 1 — Prerequisites #

Ensure Python 3.12 or higher is installed:

python --version
# Expected: Python 3.12.x or higher

Step 2 — Download the MCP Server #

After subscribing to the Redmineflux Pro Plan at redmineflux.com:

1. Log in to your account on redmineflux.com
2. Navigate to My Account → Downloads
3. Download the Redmineflux MCP Server ZIP package
4. Extract the ZIP to a folder on your machine, for example:
   • macOS / Linux: /home/yourname/redmineflux-mcp
   • Windows: C:\redmineflux-mcp
5. Open a terminal and navigate to that folder:

cd /path/to/redmineflux-mcp

Step 3 — Install Dependencies #

pip install -r requirements.txt

Or using uv (recommended for faster installs):

pip install uv
uv sync

Step 4 — Verify Installation #

python -m src.server --help

You should see the server startup options printed without errors.

Configuration #

The MCP server is configured via environment variables. These are set either in a .env file or directly in the AI client’s MCP configuration file.

Required Environment Variables #

Variable	Description	Example
REDMINE_URL	Full URL of your Redmine instance (no trailing slash)	https://redmine.mycompany.com
REDMINE_API_KEY	Your Redmine API key (see How To: Get Your API Key)	abc123def456...

Optional Environment Variables #

Variable	Default	Description
REDMINEFLUX_TIMEOUT	30	HTTP request timeout in seconds per attempt
REDMINEFLUX_TOTAL_TIMEOUT	60	Total timeout for the full request chain including retries
REDMINEFLUX_MAX_RETRIES	2	Number of retries on transient errors (502, 503, 504)
REDMINEFLUX_PLUGINS	(auto-detect)	Comma-separated list to override plugin detection, e.g. workload,timesheet
TRANSPORT	stdio	Set to sse for hosted/remote mode
HOST	0.0.0.0	Bind host (SSE mode only)
PORT	8000	Bind port (SSE mode only)

Example .env file #

REDMINE_URL=https://redmine.mycompany.com
REDMINE_API_KEY=your_api_key_here
REDMINEFLUX_TIMEOUT=30

How To: Connect Claude Desktop (Mac / Windows) #

Claude Desktop uses a local configuration file (claude_desktop_config.json) to register MCP servers.

Step 1 — Locate the Config File #

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Step 2 — Edit the Config File #

Open the file in a text editor and add the Redmineflux MCP server entry inside the mcpServers object:

{
"mcpServers": {
"redmineflux": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "/path/to/redmineflux-mcp",
"env": {
"REDMINE_URL": "https://redmine.mycompany.com",
"REDMINE_API_KEY": "your_api_key_here"
}
}
}
}

Note: Replace /path/to/redmineflux-mcp with the actual path where you downloaded the MCP server.

Windows path example: C:\\Users\\YourName\\redmineflux-mcp

Step 3 — Restart Claude Desktop #

Close and reopen Claude Desktop. On the next startup, the Redmineflux MCP tools will be available.

Step 4 — Verify Connection #

In a new Claude conversation, type:

“Show me my Redmine projects”

If the connection is successful, Claude will return your project list.

How To: Connect Claude.ai Web App #

The Claude.ai web interface supports MCP servers running in SSE (Server-Sent Events) mode. This requires the MCP server to be hosted at a publicly accessible URL.

Step 1 — Start the MCP Server in SSE Mode #

TRANSPORT=sse \
REDMINE_URL=https://redmine.mycompany.com \
REDMINE_API_KEY=your_api_key_here \
python -m src.server

The server will start on http://0.0.0.0:8000 by default.

Step 2 — Make the Server Publicly Accessible #

Options:

• Deploy behind a reverse proxy (nginx, Caddy) with HTTPS
• Use a tunneling tool like ngrok for testing: ngrok http 8000

Step 3 — Add to Claude.ai Settings #

1. Open claude.ai in your browser
2. Click your profile picture → Settings
3. Navigate to Integrations → Model Context Protocol
4. Click Add Integration
5. Enter the MCP server URL: https://your-server-url/sse
6. Click Connect

Step 4 — Authenticate Per Request #

In SSE mode, each request carries the API key via the X-Redmine-API-Key header. This allows multiple users to share one MCP server with their own Redmine credentials.

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

Claude Code is Anthropic’s official CLI and VS Code extension. It supports MCP servers natively.

Option A — Add via Claude Code CLI #

claude mcp add redmineflux \
--command "python" \
--args "-m src.server" \
--cwd "/path/to/redmineflux-mcp" \
--env REDMINE_URL=https://redmine.mycompany.com \
--env REDMINE_API_KEY=your_api_key_here

Option B — Edit .claude/mcp.json Manually #

Create or edit .claude/mcp.json in your project or home directory:

{
"mcpServers": {
"redmineflux": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "/path/to/redmineflux-mcp",
"env": {
"REDMINE_URL": "https://redmine.mycompany.com",
"REDMINE_API_KEY": "your_api_key_here"
}
}
}
}

Step — Verify in VS Code #

1. Open VS Code with the Claude extension installed
2. Open the Claude panel (sidebar)
3. Start a new conversation and type: “List my Redmine projects”
4. Claude will use the MCP tools to fetch and display your projects

How To: Get Your Redmine API Key #

The Redmine API key authenticates all MCP requests on your behalf. Each user has their own unique key.

1. Log in to your Redmine instance
2. Click your username in the top-right corner
3. Select My Account
4. Scroll to the API access key section at the bottom right
5. Click Show to reveal the key
6. Click Reset to generate a new key if needed
7. Copy the key and paste it into your MCP configuration

Important: Treat your API key like a password. Do not share it or commit it to version control. The MCP server uses this key to perform all actions — it has the same permissions as your Redmine user account.

How To: Use MCP Tools in a Conversation #

Once connected, you can interact with Redmine entirely through natural language. Claude automatically selects the right tool for your request.

Example Commands #

Issues:

• “Show all open bugs in the Mobile App project”
• “Create a new issue: ‘Fix login timeout’ in the API project, assign to John”
• “Update issue #1042 status to In Progress”
• “What are my critical issues today?”

Time Tracking:

• “Log 2.5 hours on issue #1023 for development”
• “Show time entries for the past week in the Backend project”

Agile Board:

• “Show the agile board for project ztflux”
• “Move issue #1042 to Done column”
• “Create a sprint named ‘Sprint 5’ for 2 weeks”
• “List all sprints in the Mobile project”

Workload:

• “Who is over-allocated this week?”
• “Show capacity for the development team”
• “Add a holiday on December 25th to the Default scheme”

Timesheet:

• “Submit my timesheet for this week”
• “Show pending timesheet approvals”
• “Approve timesheet for user vaishnavi.bhawsar”

Helpdesk:

• “List all open support tickets”
• “Create a new ticket from customer@example.com”
• “Show SLA status for ticket #205”

Knowledge Base:

• “List all spaces in the knowledge base”
• “Create a new KB page titled ‘API Setup Guide’ in the Dev space”

Checklists:

• “Add a checklist to issue #1042 called ‘Code Review'”
• “Mark all checklist items in checklist #5 as done”

Test Cases:

• “Create a test run for the Login module”
• “List all failed test cases in the current sprint”

How To: Check Which Plugins Are Detected #

The MCP server detects installed plugins automatically at startup. To see which plugins are active in your current session:

1. In any Claude conversation, type: “Which Redmineflux plugins are detected?” or “Show the MCP server version and installed plugins”
2. Claude will call the redmineflux_system_version tool and display output like:

Redmineflux MCP Server v0.2.2

Detected plugins:
✓ agile_board
✓ redmineflux_checklist
✓ flux_tags
✓ flux_issue_template
✓ redmineflux_knowledgebase
✓ helpdesk
✓ budget_audit
✓ invoice
✓ crm
✓ workload
✓ timesheet
✓ testcase_management

Core Redmine tools: always available

Tip: If a plugin you expect to see is missing, verify the plugin is installed and enabled in Redmine at Administration → Plugins.

Plugin Tools Overview #

Redmineflux MCP provides tools for both core Redmine functionality and all Redmineflux plugins. Core tools are always available. Plugin tools are auto-detected at startup based on which plugins are installed in your Redmine instance.

The MCP server supports plugins including: Agile Board, Workload, Timesheet, Helpdesk, Checklist, Knowledge Base, Issue Template, Invoice, CRM, Tags, Budget & Audit, and Testcase Management.

With all plugins installed, the MCP server provides over 400 tools covering every aspect of project management — from creating issues and logging time to managing sprints, approving timesheets, and handling support tickets.

Permissions Setup in Redmine #

The MCP server operates with the permissions of the Redmine user whose API key is configured. To use all features, the user must have the appropriate Redmine roles and permissions.

Minimum Permissions for Full MCP Access #

Navigate to: Administration → Roles and Permissions → [Your Role] → Save

Permission	Required For
view_issues	Reading issues, checklists, search
add_issues	Creating new issues
edit_issues	Updating issues, checklists, tags
delete_issues	Deleting issues
log_time	Logging time entries
view_time_entries	Viewing time reports
manage_project	Archiving/unarchiving projects
view_agile_board	Reading agile board data
manage_agile_board_settings	Managing columns, board settings
manage_sprints	Creating/updating sprints
manage_tags	Creating/updating/deleting tags
manage_issues_tags	Tagging issues
view_issue_templates	Listing and viewing templates
create_issue_templates	Creating project-level templates
edit_issue_templates	Editing templates
delete_issue_templates	Deleting templates

Tip: For full access without per-permission setup, grant the user Administrator access in Redmine. Administrator users bypass all permission checks on MCP API endpoints.

API Key User Best Practices #

• Create a dedicated Redmine user for MCP integrations (e.g., mcp-bot)
• Grant it the minimum permissions your team needs
• Rotate the API key periodically via My Account → API access key → Reset
• For team deployments, each user can provide their own API key in SSE mode

Troubleshooting #

Problem: “No tools available” in Claude #

Cause: The MCP server is not running or not registered correctly.

Solution:

1. Verify the cwd path in your config points to the correct directory
2. Check Python is installed: python --version
3. Run the server manually to see startup errors: cd /path/to/redmineflux-mcp && python -m src.server
4. Restart Claude Desktop after changing the config file

Problem: “Authentication failed — your API key is invalid or expired” #

Cause: The API key in the config is wrong or the user’s account is inactive.

Solution:

1. Log in to Redmine → My Account → API access key → copy the key again
2. Update the REDMINE_API_KEY in your MCP config
3. Ensure the Redmine user account is active (not locked)
4. Restart the AI client after updating the config

Problem: Plugins not detected (e.g., Agile Board tools missing) #

Cause: The plugin is not installed or not enabled in Redmine.

Solution:

1. Log in as Redmine admin
2. Navigate to Administration → Plugins and verify the plugin is listed
3. Navigate to Administration → Roles and Permissions and verify the module is enabled for the role
4. Check the module is enabled for the project under Project → Settings → Modules
5. Restart the MCP server — plugin detection runs at startup

Problem: “You do not have permission” errors #

Cause: The Redmine user behind the API key lacks the required permission for that action.

Solution:

1. Log in as Redmine admin
2. Navigate to Administration → Roles and Permissions
3. Select the role assigned to your API key user
4. Enable the required permission (see Permissions Setup)
5. Save and retry

Problem: Tool call times out or hangs #

Cause: Redmine is slow to respond or the network connection is unstable.

Solution:

1. Increase the timeout: set REDMINEFLUX_TIMEOUT=60 in your config
2. Check Redmine server health and logs
3. Retry the request — transient errors are automatically retried up to 2 times
4. If the issue persists, contact your Redmine administrator

Problem: Plugin was uninstalled but tools still appear #

Cause: Old detection cache may linger from a previous session.

Solution:

1. Restart the MCP server completely — detection runs fresh on each startup
2. Use REDMINEFLUX_PLUGINS override to explicitly list only installed plugins:

REDMINEFLUX_PLUGINS=workload,agile_board,helpdesk

Frequently Asked Questions (FAQs) #

Q1: Does Redmineflux MCP send my Redmine data to Anthropic or any third party?

No. The MCP server runs locally or on your own infrastructure. Your Redmine data is only sent to the AI model (Claude) for processing your specific request — never stored by the MCP server itself. Anthropic’s data handling follows their standard privacy policy.

Q2: Can multiple users share one MCP server?

Yes. In SSE (hosted) mode, multiple users can connect to a single MCP server instance. Each user provides their own Redmine API key via the X-Redmine-API-Key request header, so all actions are authenticated with their individual Redmine credentials and permissions.

Q3: What happens if I ask about a plugin that is not installed?

The MCP server detects installed plugins at startup and only registers tools for detected plugins. If a plugin is not installed, its tools are not available at all — Claude will simply not have those capabilities, rather than returning confusing errors.

Q4: Can I use Redmineflux MCP with Redmine instances that have custom fields?

Yes. Custom fields are fully supported. You can pass custom field values when creating or updating issues using the custom_fields parameter, e.g., [{"id": 5, "value": "Production"}].

Q5: Does it work with Redmine Cloud or self-hosted instances?

Both. As long as the MCP server machine can reach your Redmine instance via HTTP/HTTPS and you have a valid API key, it works with any Redmine deployment — cloud or self-hosted.

Q6: Can I restrict what the AI can do in Redmine?

Yes. The AI can only perform actions permitted by the Redmine user whose API key is configured. To restrict actions, create a dedicated Redmine role with only the permissions you want to allow, assign it to your MCP user, and use that user’s API key.

Q7: How many tools does Redmineflux MCP provide?

With all Redmineflux plugins installed, the MCP server provides over 400 tools across core Redmine functionality and all supported plugins. Without plugins, approximately 100 core tools are always available. See redmineflux.com for the full plugin list by plan.

Q8: Does it support multiple Redmine instances?

Each MCP server instance connects to one Redmine URL. To work with multiple instances, configure multiple MCP server entries in your AI client config — one per Redmine instance — each with a different name (e.g., redmineflux-prod, redmineflux-staging).

Q9: Is an internet connection required?

Only to reach your Redmine instance. The MCP server itself runs locally. If your Redmine is on a local network or VPN, no public internet access is needed.

Q10: What AI models work with Redmineflux MCP?

Redmineflux MCP is designed for Claude by Anthropic (Claude Desktop, Claude.ai, Claude Code). It uses the standard MCP protocol, so any MCP-compatible AI client can connect, but Claude is the recommended and tested client.

Q11: What should I do if I encounter a bug or have a feature request?

Please submit a ticket at your Redmine instance or contact the Redmineflux support team at redmineflux.com/support. Include the MCP server version (redmineflux_system_version tool) and a description of the issue.

Updates and Revisions #

• Monitor the official Redmineflux website for new MCP server releases
• Review the changelog before upgrading to understand breaking changes
• Test updates in a development or staging environment before deploying to production
• After upgrading, restart the MCP server and verify plugin detection is working
• Check that your Redmine plugin versions are compatible with the new MCP server version
• Rotate your API key periodically for security best practices

Conclusion #

Redmineflux MCP Server bridges the gap between natural language AI assistants and your Redmine project management platform. By connecting Claude to your Redmine instance, your team can perform complex project management tasks — creating issues, managing sprints, tracking time, approving timesheets, handling support tickets — through simple conversation, without ever leaving your AI assistant.

With support for all Redmineflux plugins, automatic plugin detection, per-user authentication, and user-friendly error messages, the MCP server is designed to be both powerful and approachable for teams of any size.