Agama Redmine

npm version License Node Version GitHub Issues CI Coverage npm downloads

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.

Variable	Required	Default	Purpose
REDMINE_URL	yes	—	Base URL of the Redmine instance
REDMINE_API_KEY	yes	—	API key for the acting user
REDMINE_TIMEOUT_MS	no	30000	Per-request timeout in milliseconds
REDMINE_ALLOWED_DIRECTORIES	no	empty	Directories the attachment tools may use
LOG_LEVEL	no	info	debug | info | warn | error
MCP_TRANSPORT	no	stdio	stdio (only supported mode today)

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.

Tool	Kind	Description
redmine_list_issues	read	Search/filter issues by status, assignee, tracker, dates…
redmine_get_issue	read	Full issue detail, optionally with journals and attachments
redmine_create_issue	write	Create an issue
redmine_update_issue	write	Edit an issue's status, assignee, notes…
redmine_delete_issue	write · destructive	Permanently delete an issue — no undo, cascades
redmine_manage_issue_watchers	write	Add/remove a watcher (notification subscription)
redmine_list_issue_relations	read	Dependency links of an issue, or one relation by its id
redmine_create_issue_relation	write	Link two issues (blocks, precedes, duplicates, relates…)
redmine_delete_issue_relation	write · destructive	Remove one link — narrow in scope and reversible
redmine_search	read	Free-text search across issues, wiki, news, projects
redmine_list_projects	read	List visible projects
redmine_get_project	read	Full project detail, trackers/categories/activities
redmine_list_time_entries	read	Query logged time
redmine_create_time_entry	write	Log hours against an issue or project
redmine_get_current_user	read	"Who am I" — the API key's user, memberships, groups
redmine_list_users	read	Find users by name/status/group — admin-gated on most sites
redmine_list_reference_data	read	Statuses, trackers, priorities, activities, doc categories
redmine_upload_attachment	write	Upload a local file → token for an issue's uploads array
redmine_download_attachment	write	Save an attachment to a local directory (writes to disk)

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

Symptom	Likely cause
Client shows no tools	Something besides JSON-RPC is writing to stdout — check any wrapper
Exits immediately on startup	A required env var is missing or invalid; the error names it
401 Unauthorized	API key missing/wrong, or REST API disabled on the Redmine side
403 Forbidden	The key's user lacks permission for that action
404 Not Found	The id doesn't exist or isn't visible to the key
422 Unprocessable Entity	Redmine rejected the write — check the field-level messages returned

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