Redmine Model Context Protocol (MCP) Server

A Model Context Protocol (MCP) server that connects to a Redmine instance, allowing LLM clients (such as Claude Desktop or Cursor) to interact with Redmine projects, issues, timesheets, and time logs.

Features & Tools

This server provides the following tools to the MCP client:

Tool Name	Description	Arguments / Inputs
redmine_list_projects	Lists all visible projects in Redmine.	None
redmine_list_issues	Lists issues with optional filters.	project_id (string), status_id (string, e.g. open/closed/*), assigned_to_id (string or "me"), limit (number)
redmine_get_issue	Retrieves detailed information of a specific issue by its ID.	id (number, required)
redmine_create_issue	Creates a new issue in a specific project.	project_id (string, required), subject (string, required), description (string)
redmine_get_timesheet	Gets time entries (timesheet) for the authenticated user.	from (YYYY-MM-DD), to (YYYY-MM-DD), project_id (string), limit (number), offset (number)
redmine_log_time	Logs spent hours on an issue or project.	hours (number, required), issue_id (number) or project_id (number), activity_id (number), comments (string, max 255 chars), spent_on (YYYY-MM-DD), user_id (number, requires admin permissions)
redmine_list_time_entry_activities	Lists the available time entry activities (e.g., Development, Design) and their IDs.	None
redmine_get_my_permissions	Gets current user info, project memberships, and roles.	None

Getting Started

Prerequisites

• Node.js (v18 or higher recommended)
• Access to a Redmine instance with REST API enabled (and an API key generated)

Setup & Installation

1. Install dependencies:

   npm install
   

2. Configure environment variables. Create a .env file in the root directory:

   REDMINE_URL=https://your-redmine-domain.com
   REDMINE_API_KEY=your_redmine_api_key_here
   LOG_LEVEL=info
   TRANSPORT=stdio
   PORT=3000
   

   • REDMINE_URL: The base URL of your Redmine instance (e.g., https://redmine.yourcompany.com).
   • REDMINE_API_KEY: Your personal Redmine API access key (found under the "My Account" page in Redmine).
   • LOG_LEVEL: The minimum logging severity level (e.g., info, debug, warn, error). Defaults to info.
   • TRANSPORT: The server communication protocol. Options are stdio (default) for local stdin/stdout, or sse to run the server over HTTP Server-Sent Events.
   • PORT: The port to bind to when running in sse transport mode. Defaults to 3000.

Development & Testing

• To run the server in development mode (watches for file changes using tsx):

  npm run dev
  

• To run a connection check/test script:

  npx tsx src/test.ts
  

• To build the project:

  npm run build
  

• To run the built server in production mode:

  npm start
  

Running as a Remote SSE Server

If you want to run the server remotely and connect to it over HTTP (Server-Sent Events) rather than using local stdin/stdout:

1. Configure .env to use the sse transport and define a port:

   TRANSPORT=sse
   PORT=3000
   

2. Start the server:

   npm start
   

   (Or run npm run dev to run it with tsx watch in development mode)

3. The server will run on http://localhost:3000 (or your configured port).

   • The SSE connection endpoint is: GET /sse
   • The client message endpoint is: POST /messages

Integration with MCP Clients

Claude Desktop

To use this server with Claude Desktop, add it to your claude_desktop_config.json configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server configuration under the mcpServers object:

{
  "mcpServers": {
    "redmine-mcp": {
      "command": "node",
      "args": [
        "/path/to/redmine-mcp/dist/server.js"
      ],
      "env": {
        "REDMINE_URL": "https://your-redmine-domain.com",
        "REDMINE_API_KEY": "your_redmine_api_key_here"
      }
    }
  }
}

Make sure to run npm run build in the server directory before starting Claude Desktop so that dist/server.js exists.

Technical Details

• Stdio Transport: The server communicates via standard input/output.
• Stderr Logging: Because the stdout stream is dedicated strictly to JSON-RPC messages for the MCP protocol, all server application logs (using Pino) are routed to process.stderr to prevent protocol stream corruption.
• Old Redmine Compatibility: The redmine_log_time tool sends XML-formatted POST requests to /time_entries.xml. This prevents potential 404 errors on older Redmine instances (such as those running on Ruby 1.8.7) which do not support JSON payloads for creating time entries.