{ "markdown": "

\n \n \n \"redmine-mcp-stdio\n \n

\n\n# redmine-mcp-stdio\n\nA local [Model Context Protocol](https://modelcontextprotocol.io) server (stdio) for [Redmine](https://www.redmine.org). Point an MCP client at it (Cursor, VS Code, Claude, Codex, Windsurf, Cline, Zed, JetBrains AI and others) and work with Redmine issues, projects and time entries straight from the editor.\n\n[![npm](https://img.shields.io/npm/v/redmine-mcp-stdio)](https://www.npmjs.com/package/redmine-mcp-stdio) [![npm downloads](https://img.shields.io/npm/dm/redmine-mcp-stdio)](https://www.npmjs.com/package/redmine-mcp-stdio) [![CI](https://github.com/andrelaptenok/redmine-mcp-stdio/actions/workflows/ci.yml/badge.svg)](https://github.com/andrelaptenok/redmine-mcp-stdio/actions/workflows/ci.yml) ![license](https://img.shields.io/badge/license-MIT-green) ![node](https://img.shields.io/badge/node-%3E%3D20-blue)\n\n## Tools\n\n| Tool | What it does | Key parameters |\n| ------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |\n| `list_issues` | List/filter issues, paginated | `project_id`, `status_id`, `assigned_to_id`, `query`, `limit`, `offset`, `all` |\n| `get_issue` | Full details of one issue + comments/history + attachments | `id`, `include_journals` (default `true`) |\n| `list_projects` | Accessible projects | `limit` |\n| `get_project` | Project details, versions and members | `id` |\n| `create_issue` | Create an issue | `project_id`, `subject`, `description`, `tracker_id`, `priority_id`, `assigned_to_id`, `status_id` |\n| `update_issue` | Update issue fields | `id` + any of `subject`, `status_id`, `priority_id`, `assigned_to_id`, `done_ratio`, `notes` |\n| `add_comment` | Add a note to an issue | `id`, `notes` |\n| `log_time` | Log a time entry on an issue/project | `issue_id` or `project_id`, `hours`, `activity_id`, `comments`, `spent_on` |\n| `list_time_entries` | List time entries, filtered | `issue_id`, `project_id`, `user_id`, `from`, `to`, `limit`, `offset` |\n| `list_enumerations` | IDs of trackers/statuses/priorities/activities | none |\n| `search` | Full-text search (issues, wiki, news, …) | `q`, `project_id`, `types`, `titles_only`, `open_issues`, `limit`, `offset` |\n| `get_current_user` | Account behind the API key (id, login, name) | none |\n\nEvery tool ships MCP [tool annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations) (`readOnlyHint`, `destructiveHint`, …), so clients can auto-approve read-only calls.\n\n## Install\n\nNo manual install needed. The client launches the server on demand with `npx`, which\ndownloads it on first run and caches it after. Just add the config for your client under\n[Connect](#connect).\n\nPrefer to run from a local clone? See [Development](#development).\n\n## Get a Redmine API key\n\n**My account > API access key > Show.**\n\n- If there's no such section, an admin must enable the REST API in **Administration > Settings > API**.\n- The key must belong to a user with permission to view (and, for writes, create/edit) issues.\n\n> ⚠️ Never commit your API key. Copy `.env.example` to `.env` for local use; `.env` is gitignored.\n\n## Connect\n\nThe server reads `REDMINE_URL` and `REDMINE_API_KEY` from the environment. Provide them via the client's MCP config `env` block.\n\n### Cursor\n\nEdit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in a project root:\n\n```json\n{\n \"mcpServers\": {\n \"redmine\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"redmine-mcp-stdio\"],\n \"env\": {\n \"REDMINE_URL\": \"https://redmine.your-company.com\",\n \"REDMINE_API_KEY\": \"your_key\"\n }\n }\n }\n}\n```\n\nReload Cursor and enable the server in **Settings > MCP**.\n\n### VS Code (GitHub Copilot)\n\nEdit `.vscode/mcp.json` in your workspace (or your user `mcp.json`). Note the top-level key is `servers`, not `mcpServers`:\n\n```json\n{\n \"servers\": {\n \"redmine\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"redmine-mcp-stdio\"],\n \"env\": {\n \"REDMINE_URL\": \"https://redmine.your-company.com\",\n \"REDMINE_API_KEY\": \"your_key\"\n }\n }\n }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add redmine \\\n --env REDMINE_URL=https://redmine.your-company.com \\\n --env REDMINE_API_KEY=your_key \\\n -- npx -y redmine-mcp-stdio\n```\n\nOr edit `~/.claude.json` / the project `.mcp.json` directly (same shape as Claude Desktop below).\n\n### Claude Desktop\n\nEdit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"redmine\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"redmine-mcp-stdio\"],\n \"env\": {\n \"REDMINE_URL\": \"https://redmine.your-company.com\",\n \"REDMINE_API_KEY\": \"your_key\"\n }\n }\n }\n}\n```\n\nRestart Claude Desktop afterwards.\n\n### Codex CLI\n\nAdd a server table to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.redmine]\ncommand = \"npx\"\nargs = [\"-y\", \"redmine-mcp-stdio\"]\nenv = { REDMINE_URL = \"https://redmine.your-company.com\", REDMINE_API_KEY = \"your_key\" }\n```\n\nIf node is installed via nvm, use the full path from `which npx` as `command`.\n\n### Windsurf\n\nEdit `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"redmine\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"redmine-mcp-stdio\"],\n \"env\": {\n \"REDMINE_URL\": \"https://redmine.your-company.com\",\n \"REDMINE_API_KEY\": \"your_key\"\n }\n }\n }\n}\n```\n\nIn Cascade, open **MCP servers > Manage > View raw config**, paste, then refresh. Supports `${env:VAR}` interpolation if you'd rather not inline the key.\n\n### Cline\n\nIn the Cline pane, click the **MCP Servers** icon and choose **Configure MCP Servers** to open `cline_mcp_settings.json`:\n\n```json\n{\n \"mcpServers\": {\n \"redmine\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"redmine-mcp-stdio\"],\n \"env\": {\n \"REDMINE_URL\": \"https://redmine.your-company.com\",\n \"REDMINE_API_KEY\": \"your_key\"\n }\n }\n }\n}\n```\n\n### Zed\n\nZed calls MCP servers **context servers**. Open the command palette and run **zed: open settings**, then add to `settings.json` (note `\"source\": \"custom\"`):\n\n```json\n{\n \"context_servers\": {\n \"redmine\": {\n \"source\": \"custom\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"redmine-mcp-stdio\"],\n \"env\": {\n \"REDMINE_URL\": \"https://redmine.your-company.com\",\n \"REDMINE_API_KEY\": \"your_key\"\n }\n }\n }\n}\n```\n\nZed restarts the server on save, so no editor reload is needed.\n\n### JetBrains AI Assistant (2025.2+)\n\n**Settings > Tools > AI Assistant > Model Context Protocol (MCP) > Add:**\n\n- Type: **stdio**\n- Command: `npx` (if node is installed via nvm, use the full path from `which npx`)\n- Arguments: `-y redmine-mcp-stdio`\n- Environment:\n - `REDMINE_URL=https://redmine.your-company.com`\n - `REDMINE_API_KEY=your_key`\n\nEnable _\"Automatically enable new and changed MCP servers\"_, then **Apply**. Click the status icon and you should see 12 tools. Invoke them in chat with `/`.\n\n## Verify locally (optional)\n\n```bash\nREDMINE_URL=https://redmine.your-company.com REDMINE_API_KEY=your_key npx -y redmine-mcp-stdio\n```\n\nThe process should start and wait silently on stdio (Ctrl+C to exit).\n\n## Troubleshooting\n\n- **`Failed to connect` / server won't start:** the `command` must resolve in the client's environment. If node is installed via nvm, a bare `npx` may not be found. Use the full path from `which npx` as the command.\n- **`Missing REDMINE_URL or REDMINE_API_KEY`:** the `env` block wasn't passed. Double-check it's in the MCP config, not your shell.\n- **`Redmine 401` / `403`:** bad API key, or the key's user lacks permission for that action.\n- **`Redmine 404`:** the issue/project id doesn't exist, or `REDMINE_URL` points at the wrong host.\n\n## Configuration\n\n| Variable | Required | Default | Description |\n| --------------------- | -------- | ------- | ----------------------------------------------- |\n| `REDMINE_URL` | yes | n/a | Base URL of your Redmine instance (http/https) |\n| `REDMINE_API_KEY` | yes | n/a | Personal API access key |\n| `REDMINE_TIMEOUT_MS` | no | `10000` | Per-request timeout in milliseconds |\n| `REDMINE_MAX_RETRIES` | no | `2` | Retries on `429`/`5xx` with exponential backoff |\n\n## Architecture\n\nThe code is organized in layers, with a single HTTP client injected into each tool\ngroup so that tools never touch transport or `process.env` directly:\n\n```\nsrc/\n index.ts entry point: load config, build client, register tools, serve stdio\n config.ts env parsing + validation (Zod) into a typed RedmineConfig\n version.ts single source of the version string\n redmine/\n client.ts RedmineClient: auth, timeout, retry, host pinning, secret redaction\n errors.ts RedmineError / ConfigError + HTTP error normalization\n paths.ts safe path-segment encoding + project-id validation\n types.ts Redmine API response types\n tools/\n register.ts wires every tool group onto the server\n issues.ts list/get/create/update issues + add_comment\n projects.ts list/get projects (versions, members)\n time-entries.ts log_time, list_time_entries\n enumerations.ts trackers / statuses / priorities / activities\n search.ts full-text search across issues, wiki, news, ...\n users.ts get_current_user\n helpers.ts guard(), ok()/fail(), ToolResult\n format.ts pure presentation helpers\n```\n\n## Development\n\n```bash\nnpm run build # compile src/ to build/\nnpm run typecheck # tsc --noEmit (strict)\nnpm run lint # eslint\nnpm run format # prettier --write\nnpm test # build, then run the vitest suite\nnpm run check # typecheck + lint + format:check + test (what CI runs)\n```\n\nSee [CHANGELOG.md](./CHANGELOG.md) for releases.\n\n## Security\n\nThe API key is never logged and is redacted from error output; requests are pinned to\nthe configured host, path parameters are encoded, and every call is bounded by a\ntimeout and a response-size cap. Details and reporting: [SECURITY.md](./SECURITY.md).\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n", "bytes": 11663, "sha": "a23c1e531cfab9ef04ad5334938c7956f52c523a4925077cf125040986e47b48", "repo_slug": "andrelaptenok/redmine-mcp-stdio", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_andrelaptenok_redmine_mcp_stdi_36053002/readme" }