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:

Related MCP server: redmine-mcp-server

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.