Redmineflux MCP Server

Why Redmineflux MCP Server?

Redmine holds your project data — issues, time entries, milestones, workload, agile boards, knowledge base articles. But accessing that data means clicking through multiple pages, running custom queries, and switching between plugins.

Redmineflux MCP Server makes all of that accessible to AI agents. Your team asks questions in natural language and gets answers backed by live project data. AI agents can read, create, and update issues, log time, check workload, and query across all your projects — in seconds.

Team member asks a question → AI Agent → MCP Server → Redmine REST API → Answer

Redmine holds the data. Redmineflux plugins enrich it. The MCP server makes it accessible to AI agents. Your team keeps working the way they always have — but now they can ask "what should I work on first?" or "how many bugs are open in Phoenix?" and get answers in seconds.

Related MCP server: Redmine MCP Server

Why a Standalone Service? Why Python?

If you're a Redmineflux customer, you're used to plugins: drop into plugins/, run migrations, restart Redmine, done. So why is the MCP server different?

MCP servers and Redmine plugins serve different audiences through different protocols. A Redmine plugin renders HTML for humans in browsers over HTTP. An MCP server streams structured data to AI agents over stdio/SSE. These are fundamentally different runtime models — combining them would compromise both.

Why Python specifically:

• Official SDK — Anthropic maintains the MCP Python SDK. Protocol changes are handled upstream. A Ruby implementation would mean building and maintaining the protocol from scratch.

• Ecosystem — every major MCP server (GitHub, Slack, Notion, Linear) is Python or TypeScript. Customers using AI agents already expect this pattern.

• Async HTTP — Python's httpx provides native async/await for efficient Redmine API communication.

• AI/ML ready — if we add features like embeddings or summarization later, the Python ecosystem is already there.

Your Redmine stays untouched. The MCP server is a companion service that connects to Redmine through its standard REST API — the same API your browser uses. No database access, no Redmine internals, no risk to your existing setup.

For the full architectural decision record, see the Decision Document.

Key Features

• 51 MCP Tools — full CRUD for issues, projects, time entries, users, versions, plus plugin-specific tools for DevOps, Timesheet, Workload, Agile Board, and Knowledge Base

• Capability Injection — auto-detects which Redmineflux plugins are installed on your Redmine instance and loads only the relevant tools

• Natural Language Access — ask questions about projects, issues, time, and milestones without learning Redmine's UI

• Cross-Project Queries — "compare bugs across all 6 projects" in one question instead of 6 browser tabs

• One-Sentence Actions — "log 4 hours and update to 80% done" replaces two separate Redmine forms

• Observability — every tool call logged as JSON Lines with session tracking, user identity, and timing

• MCP Standard — works with Claude Code, ChatGPT, GitHub Copilot, and any MCP-compatible AI agent

Tools

Core Tools (15)

Convenience Tools (5)

System Tools (1)

Plugin Tools (30)

Plugin tools are automatically loaded when the corresponding Redmineflux plugin is detected on your Redmine instance.

Screenshots

Screenshots coming soon — the MCP server is in active development.

Requirements

Installation

1. Clone

git clone https://github.com/zehntech/redmineflux-mcp.git
cd redmineflux-mcp

2. Install Dependencies

pip install -e .

3. Configure

cp .env.example .env
# Edit .env with your Redmine URL and API key

4. Connect to Your AI Agent

Option A: Generate config automatically (recommended for teams)

python3 -m src.setup

This auto-detects the install path and generates a ready-to-use .mcp.json. Admin runs it once, sends the output to the team — each person just replaces YOUR_API_KEY with their own Redmine API key.

Option B: Manual setup

Add to your project's .mcp.json:

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

Finding your API key: Redmine → My Account → API access key (right sidebar) → Show

The server communicates over stdio (standard MCP transport). Any MCP-compatible AI agent can connect using the same command.

5. Auto-Start on Boot (Optional)

If you're running the MCP server on a shared team server, you'll want it to start automatically.

Linux (systemd):

Create /etc/systemd/system/redmineflux-mcp.service:

[Unit]
Description=Redmineflux MCP Server
After=network.target

[Service]
Type=simple
User=redmine
WorkingDirectory=/opt/redmineflux-mcp
ExecStart=/opt/redmineflux-mcp/.venv/bin/python -m src.server
EnvironmentFile=/opt/redmineflux-mcp/.env
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable redmineflux-mcp
sudo systemctl start redmineflux-mcp

# Check status
sudo systemctl status redmineflux-mcp

macOS (launchd):

Create ~/Library/LaunchAgents/com.redmineflux.mcp.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.redmineflux.mcp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/redmineflux-mcp/.venv/bin/python</string>
        <string>-m</string>
        <string>src.server</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/opt/redmineflux-mcp</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>REDMINE_URL</key>
        <string>https://redmine.example.com</string>
        <key>REDMINE_API_KEY</key>
        <string>your_api_key</string>
    </dict>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/var/log/redmineflux-mcp.log</string>
    <key>StandardErrorPath</key>
    <string>/var/log/redmineflux-mcp.error.log</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.redmineflux.mcp.plist

# Check status
launchctl list | grep redmineflux

Docker:

docker run -d --name redmineflux-mcp \
  --restart unless-stopped \
  -e REDMINE_URL=https://redmine.example.com \
  -e REDMINE_API_KEY=your_api_key \
  redmineflux/mcp-server:latest

Note: For Claude Code's .mcp.json integration, auto-start is not needed — Claude Code launches the MCP server process automatically when it connects. Auto-start is for shared team servers where the MCP server runs as an HTTP/SSE endpoint for multiple agents.

Usage

Once connected, ask questions naturally:

You: What's the status of the Phoenix Platform project?
AI:  Phoenix Platform has 1,594 issues — 33% complete.
     New: 537 | In Progress: 304 | Resolved: 93 | Closed: 538
     Next milestone: v0.4 Frontend Shell (due 2026-03-31)

You: Show me critical bugs
AI:  10 critical issues (Urgent + Immediate) across 4 projects...

You: Log 4 hours of Development on issue #50, comment "API refactoring complete"
AI:  Logged 4.0h on issue #50 (entry id=1846)

You: I just joined the team, where do I start?
AI:  Welcome! You're assigned to 3 projects with 42 open issues...

Access Control & Permissions

The MCP server respects Redmine's permission model. You only see what your API key allows.

Each person connects with their own Redmine API key. That key inherits the same permissions as their Redmine user account — same projects, same roles, same visibility. If you can't see a project in Redmine's web UI, you won't see it through the MCP server either.

What Happens When You Don't Have Access

The server handles permission issues gracefully with clear messages:

You: Show me the status of the Secret-Project
AI:  Not found: project 'Secret-Project' does not exist, or you don't have
     permission to see it. Redmine returns 404 for both missing resources and
     resources you lack access to. Verify the ID is correct, or ask your
     Redmine administrator for access.

You: List all users
AI:  Access denied: you don't have permission to view users. Your API key
     only provides access to resources your Redmine account has been granted.
     Listing all users requires an admin API key. To see what you DO have
     access to, try listing your projects or checking your current user details.

Common Scenarios

Best Practices for Admins

• Give each person their own API key — don't share a single admin key. This ensures audit logs show who did what, and each person only sees their projects.

• Use the setup script (python3 -m src.setup) to generate the config with your Redmine URL pre-filled. Send it to the team — they just add their own API key.

• Admin keys see everything — only use admin keys for system-level agents (CI/CD bots, reporting agents), not for individual team members.

Who Is This For?

Architecture

┌──────────────┐     ┌───────────────────────┐     ┌──────────────┐
│  AI Agent    │     │  Redmineflux MCP      │     │  Redmine     │
│  (Claude,    │────▶│  Server (Python)      │────▶│  REST API    │
│   ChatGPT,   │◀────│                       │◀────│              │
│   Copilot)   │     │  51 tools             │     │  + Plugins   │
└──────────────┘     │  Capability injection │     └──────────────┘
                     │  Observability layer  │
                     │  JSON audit logs      │
                     └───────────────────────┘

Modular design: Core tools (21) are always loaded. Plugin tools (30) are injected based on which Redmineflux plugins are installed on your Redmine instance — the server auto-detects capabilities at startup.

Security

The MCP server uses stdio transport — it runs as a local process with no network endpoint.

Best practices: Use personal API keys (not shared admin keys), keep .env out of git, revoke keys immediately if compromised.

For the full security analysis, see How MCP Routing Works.

Works With

FAQ

Q: Does the MCP server require direct database access? No. The server communicates exclusively through Redmine's REST API. No database credentials or direct connections needed.

Q: Which AI agents are supported? Any agent that supports the Model Context Protocol (MCP) — Claude Code, ChatGPT (with MCP plugin), GitHub Copilot, and custom agents built with the Anthropic SDK.

Q: Do I need all Redmineflux plugins installed? No. The server auto-detects which plugins are available and loads only the relevant tools. Core Redmine tools (21) always work, even without any Redmineflux plugins installed.

Q: Is my data sent to third parties? The MCP server runs locally on your machine. It communicates with your Redmine instance via its REST API. Your project data stays between the server and your Redmine — the MCP server does not send data anywhere else.

Q: Can I restrict which tools are available? Yes. The server respects Redmine's permission model — users only see data they have access to based on their API key's role and project memberships.

Q: What about audit logging? Every tool call is logged as JSON Lines in the logs/ directory with session ID, user identity, tool name, parameters, timing, and result status. Sensitive fields are redacted automatically.

Q: Can I see MCP activity inside Redmine? A Redmine dashboard plugin is planned (Phase 6) that will show connection status, agent activity feed, and usage statistics directly in the Redmine UI. The MCP server itself remains external — the dashboard reads its audit logs.

Beta Mode

The MCP server ships with beta mode enabled by default. When active, every AI response includes a notice directing users to report issues:

This is a BETA version of Redmineflux MCP Server. If you encounter any issues or have feedback, please log a ticket on the 'ztmcp' project in Redmine.

This works through the MCP instructions field — the AI agent reads it on connect and appends the notice to every response. No tool output is modified.

Configuration:

To disable beta mode when going to GA: set REDMINEFLUX_BETA=false in your .env — no code change or restart needed beyond reloading the server.

Roadmap

Phase 6 Preview: MCP Dashboard Plugin

A lightweight Redmine plugin (redmineflux_mcp_dashboard) that gives project managers and admins visibility into how AI agents are interacting with their Redmine data — without leaving the Redmine UI.

Planned features:

• Connection status — is the MCP server online? Last heartbeat, uptime, version

• Live activity feed — recent tool calls: who asked what, which tool, when, how long

• Usage dashboard — calls per day, most-used tools, busiest projects, response times

• Agent sessions — which AI agents connected, session duration, tools used per session

• Audit log viewer — searchable view of the MCP server's JSON Lines audit logs

This plugin reads the MCP server's audit logs — it does NOT embed MCP functionality into Redmine. The MCP server remains a standalone Python service; the dashboard is a read-only window into its activity.

Release Notes

v0.2.0 (2026-03-30)

• Beta mode — configurable notice appended to every AI response, directing users to log feedback tickets. Toggle with REDMINEFLUX_BETA=true/false.

• Graceful permission handling — human-readable error messages for 401 (invalid key), 403 (access denied), 404 (not found / no access), and 422 (validation). Explains what went wrong and how to fix it.

• Team setup script — python3 -m src.setup auto-generates .mcp.json with correct paths. Admin runs once, sends to team.

• Access control documentation — 10 permission denial scenarios (ACL-01 through ACL-10) added to test suite and use cases.

• Architecture decision record — documented why the MCP server is a standalone Python service, not a Redmine plugin.

• Auto-start guides — systemd (Linux), launchd (macOS), and Docker instructions for running as a service.

• MCP Dashboard spec — Phase 6 roadmap for a Redmine plugin that shows MCP activity, agent sessions, and usage stats.

v0.1.0 (2026-03-29)

• Initial release with 51 MCP tools (21 core + 30 plugin)

• Capability injection — auto-detects installed Redmineflux plugins

• Observability layer with JSON Lines audit logging

• 5 plugin modules: DevOps, Timesheet, Workload, Agile Board, Knowledge Base

• Docker development environment (Redmine 5.1 + PostgreSQL 16)

• 47 integration tests, Claude API e2e test, role-based scenario tests

Support

• Knowledge Base: redmineflux.com/knowledge-base

• Email: support@redmineflux.com

• Website: redmineflux.com