Redmine MCP Server

A read-only Model Context Protocol (MCP) server for querying Redmine issue data via the Redmine REST API. Designed to integrate seamlessly with AI assistants (e.g., Claude, Cursor, GitHub Copilot) that support MCP.

Features

• 🔍 Read-only access to Redmine — list issues, get issue details, query metadata
• 🔐 Flexible authentication — API key or HTTP Basic Auth (or both combined)
• 📦 Toolset system — enable only the tools you need
• 🔤 Configurable tool prefix — avoid naming conflicts across multiple MCP servers
• 🪙 Token limiting — automatically truncates oversized responses to avoid context overflow
• 🚀 Zero local install — run directly via npx without cloning the repo

Available Tools

Toolset: issue

Tool	Description	Redmine Endpoint
get_issues	List issues with rich filters	GET /issues.json
get_issue	Get a single issue with associated data	GET /issues/:id.json
get_attachments	List attachments for an issue	GET /issues/:id.json
download_attachment	Download an attachment as base64 (≤ 10 MB) or stream to disk via outputPath	GET /attachments/:id.json

Toolset: issue_metadata

Tool	Description	Redmine Endpoint
get_trackers	List all trackers	GET /trackers.json
get_issue_statuses	List all issue statuses	GET /issue_statuses.json
get_issue_priorities	List all issue priorities	GET /enumerations/issue_priorities.json
get_issue_categories	List categories for a project	GET /projects/:id/issue_categories.json
get_issue_relations	List relations for an issue	GET /issues/:id/relations.json

Tools are prefixed with the value of PREFIX (e.g., redmine_get_issues). See Configuration for details.

Quick Start

Requirements

• Node.js 20+ (uses built-in fetch and ES modules)
• A running Redmine instance with the REST API enabled
• A valid API key or username/password credentials

Installation (via npx)

Add this to your MCP client configuration (e.g., Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["github:danglephuc/redmine-mcp-server"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your-api-key-here",
        // "REDMINE_USERNAME": "your-username",
        // "REDMINE_PASSWORD": "your-password",
        "MAX_TOKENS": "50000",
        "PREFIX": "redmine_",
        "ENABLE_TOOLSETS": "issue,issue_metadata",
      },
    },
  },
}

See Configuration for all available environment variables and CLI flags.

Documentation

Document	Description
Configuration	All environment variables, CLI flags, and auth options
Tools Reference	Detailed parameters and examples for every tool
Architecture	Project structure, key modules, and extension guide
Development	How to run, build, test, and extend this project

Development

npm install
npm run dev          # run with tsx (hot reload)
npm run inspect      # launch MCP Inspector UI at http://localhost:6274
npm run build        # type-check and compile to build/
npm run test         # run all tests with vitest
npm run test:coverage  # run tests with coverage
npm run lint         # lint with eslint
npm run format       # check formatting with prettier

License

MIT