🦎 Agama — Redmine MCP Server

MCP server for Redmine. Enables AI agents to work with issues using simple natural language commands.

Works just as well as a personal tool for a single developer — or deployed once and shared by the whole team.

┌──────────┐   MCP (stdio)   ┌─────────────────────┐   REST/JSON   ┌──────────┐
│  Agent   │ ──────────────▶ │  Redmine MCP Server │ ────────────▶ │ Redmine  │
│ (client) │ ◀────────────── │   (this project)    │ ◀──────────── │  server  │
└──────────┘   tool results  └─────────────────────┘     HTTP      └──────────┘

💬 Just ask

"What issues are assigned to me? Sort them by priority."

"Create a bug in the Web project: login button doesn't respond on mobile, mark it urgent."

"Summarize issue #456 and all its subtasks."

"How many hours did I log this week, broken down by project?"

Requirements

• Node.js 22+

• A Redmine instance with the REST API enabled (Administration → Settings → API)

• A Redmine API key — go to My account → API access key while signed in

Quick start

Most MCP clients (e.g. Claude Desktop) launch the server for you — configure it once and forget it:

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@0xkillaflow/agama-redmine-mcp"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your-redmine-api-key"
      }
    }
  }
}

For Claude Desktop, this goes in claude_desktop_config.json (Settings → Developer → Edit Config). Restart the client and the Redmine tools will appear in its tool list.

To run it standalone from a shell instead:

REDMINE_URL=https://redmine.example.com REDMINE_API_KEY=your-redmine-api-key \
  npx -y @0xkillaflow/agama-redmine-mcp

The server speaks MCP over stdio and logs to stderr, so stdout stays clean for the protocol.

Configuration

Set via environment variables, validated at startup. See .env.example for a template.

File access (REDMINE_ALLOWED_DIRECTORIES)

The attachment tools are the only ones that touch your filesystem, and they may only touch it inside this allowlist — a :-separated list of absolute directories (; on Windows). It governs both directions: reads for redmine_upload_attachment and writes for redmine_download_attachment.

REDMINE_ALLOWED_DIRECTORIES=/Users/you/redmine-files:/tmp/redmine-downloads

It defaults to empty, which means no local file access at all — both tools refuse every path until you opt in. That default is deliberate: an agent that can be talked into uploading a file is an agent that can be talked into uploading ~/.ssh/id_rsa or the .env holding your API key. Allowlist the narrowest directory that does the job. Paths are fully resolved (.. segments and symlinks included) before the check, so a symlink inside an allowed directory cannot point out of it, and downloads never overwrite an existing file.

Tools

Nineteen intent-shaped tools, each tagged with MCP safety annotations. Full reference: docs/tools.md.

Heads up: redmine_delete_issue is the tool that destroys data — Redmine has no trash, and the delete takes the issue's comments, time entries, attachments, and relations with it. It is annotated destructiveHint: true so an MCP client can require confirmation; if your client does not gate on that, treat every call as final. redmine_delete_issue_relation carries the same annotation but is far narrower: it removes one link between two issues, and redmine_create_issue_relation puts it back in a single call.

Heads up: on write, Redmine silently ignores an unknown tracker_id, status_id, or fixed_version_id instead of erroring — always check the returned issue. The same applies to is_private, which is silently dropped if your role lacks the "set public/private" permission.

Security

The server runs locally and acts as a single user: your REDMINE_API_KEY never leaves your machine except as a request header to your own Redmine instance, and the server can do nothing your account couldn't already do. Multi-user HTTP transport is planned but not yet implemented — selecting MCP_TRANSPORT=http exits with a clear error.

Local file access is off by default and confined to REDMINE_ALLOWED_DIRECTORIES when you enable it. Nothing else in the server reads or writes your filesystem.

Troubleshooting

Documentation

• docs/architecture.md — design and request lifecycle

• docs/tools.md — generated per-tool reference

• docs/adding-a-tool.md — recipe for adding a new tool

• CONTRIBUTING.md — dev setup and contribution guide

Development

npm install       # install dependencies
npm run dev       # watch-run the stdio server
npm test          # run the test suite
npm run build     # bundle to dist/

License

MIT