🦎 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 20+
• 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
LOG_LEVEL	no	info	debug | info | warn | error
MCP_TRANSPORT	no	stdio	stdio (only supported mode today)

Tools

Ten 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_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

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.

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