@flor3z-github/mcp-server-redmine

v1.2.0

Published

a month ago

Model Context Protocol server for Redmine integration

Downloads

0High
0Medium
0Low

flor3z

mcp model-context-protocol redmine project-management issue-tracking ai-agent

Redmine MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Redmine project management systems. This server provides comprehensive access to Redmine's features including issues, projects, time tracking, users, wiki pages, file management, and more.

Quick Start

Stdio (Claude Desktop / VS Code)

# 1. Get your Redmine API key from: My account → API access key → Show

# 2. Add to Claude Desktop config (~/.config/Claude/claude_desktop_config.json):
{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@flor3z-github/mcp-server-redmine"],
      "env": {
        "REDMINE_URL": "https://your-redmine.com",
        "REDMINE_API_KEY": "your-api-key"
      }
    }
  }
}

# 3. Restart Claude Desktop and start asking questions like:
#    "Show me all open issues assigned to me"

HTTP (Claude Code / Multi-user)

# 1. Start the server
REDMINE_URL=https://your-redmine.com npm run start:http

# 2. Connect from Claude Code (browser opens for API Key input)
claude mcp add redmine http://localhost:3000/mcp

Features

Issue Management

List, search, and filter issues
Create, update, and delete issues
View issue details with relationships and history

Project Management

List all projects
View project details and metadata
Access project versions/milestones

Time Tracking

Log time entries
View and manage time records
List time entry activities

User Management

List users and groups
Get user details and memberships
Access current user information

Wiki Management

List wiki pages with hierarchy
Create, update, and delete wiki pages
View wiki page history

File & Attachment Management

List, upload, and manage project files
Get, update, and delete attachments
Update journal notes

Utilities

List issue statuses, priorities, and trackers
Custom API requests for advanced use cases
Search issues, wiki pages, and more

Prerequisites

Node.js >= 20.0.0
A Redmine instance with API access enabled
Redmine API key or username/password

Installation

Global Installation (recommended)

npm install -g @flor3z-github/mcp-server-redmine

Direct Usage (no installation required)

npx @flor3z-github/mcp-server-redmine

For local development

# Clone the repository
git clone https://github.com/flor3z-github/redmine-mcp-server.git
cd redmine-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Environment Variables

Configure the server using environment variables:

# Required
REDMINE_URL=https://your-redmine-instance.com

# Authentication (required for stdio mode, optional for HTTP mode)
REDMINE_API_KEY=your-api-key-here
# Or basic auth:
# REDMINE_USERNAME=your-username
# REDMINE_PASSWORD=your-password

# Optional: SSL configuration
# REDMINE_SSL_VERIFY=true
# REDMINE_CA_CERT=/path/to/ca.crt

# Optional: Request configuration
# REDMINE_REQUEST_TIMEOUT=30000
# REDMINE_MAX_RETRIES=3

# Optional: Transport configuration
# MCP_TRANSPORT=stdio          # "stdio" (default) or "streamable-http"
# MCP_PORT=3000                # HTTP server port (default: 3000)
# MCP_HOST=127.0.0.1           # HTTP bind host (default: 127.0.0.1)

# Optional: OAuth / TLS (HTTP transport only)
# MCP_ISSUER_URL=https://public-url  # Override OAuth issuer URL (for reverse proxy)
# MCP_DATA_DIR=/data                 # Directory for persistent OAuth data
# MCP_TLS_CERT=/path/to/server.crt   # TLS certificate file
# MCP_TLS_KEY=/path/to/server.key    # TLS private key file

CLI arguments --transport, --port, --host are also supported and take precedence over environment variables.

Getting a Redmine API Key

Log in to your Redmine instance
Go to "My account" (top right)
Click on "API access key" in the sidebar
Click "Show" to reveal your API key
Use the API key in your MCP configuration

Usage with Claude Desktop

Using the published package

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@flor3z-github/mcp-server-redmine"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using local development version

{
  "mcpServers": {
    "redmine": {
      "command": "node",
      "args": ["/path/to/redmine-mcp-server/dist/index.js"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage with HTTP Transport (Streamable HTTP)

The HTTP transport enables multi-user deployments with OAuth 2.1 authentication. Each user authenticates with their own Redmine API Key via a browser-based flow.

# Development (localhost, no TLS required)
REDMINE_URL=https://your-redmine.com npm run dev:http

# Production
REDMINE_URL=https://your-redmine.com npm run start:http

# Custom port
MCP_PORT=8080 REDMINE_URL=https://your-redmine.com npm run dev:http

Authentication (OAuth 2.1)

The HTTP transport uses MCP SDK's built-in OAuth 2.1 flow. When a client connects:

The SDK discovers the OAuth server via /.well-known/oauth-authorization-server
The client dynamically registers via /register
A browser window opens showing the API Key input form
The user enters their Redmine API Key
The server validates the key against Redmine (/users/current.json)
An OAuth access token is issued and the client proceeds

User experience:

$ claude mcp add redmine https://your-server:3000/mcp
→ "needs authentication" → "Authenticate"
→ Browser opens → Enter Redmine API Key → Submit
→ Authentication complete, MCP tools are available

Tokens are persisted to disk (MCP_DATA_DIR), so users don't need to re-authenticate on server restart. Access tokens expire after 30 days; refresh tokens are rotated automatically.

Connecting from Claude Code

# Local development (HTTP)
claude mcp add redmine http://localhost:3000/mcp

# Production (HTTPS)
claude mcp add redmine https://your-server:3000/mcp

Client JSON configuration (HTTP)

{
  "mcpServers": {
    "redmine": {
      "url": "https://your-server:3000/mcp"
    }
  }
}

TLS / HTTPS Configuration

For production deployments, configure TLS with environment variables:

MCP_TLS_CERT=/path/to/server.crt
MCP_TLS_KEY=/path/to/server.key

Generate a self-signed certificate for internal use:

mkdir -p certs
openssl req -x509 -newkey rsa:2048 -keyout certs/server.key -out certs/server.crt \
  -days 365 -nodes -subj "/CN=your-server-hostname"

| Environment | TLS Config | issuerUrl | Notes | |-------------|-----------|-----------|-------| | Local dev | None | http://localhost:3000 | SDK allows HTTP for localhost | | Direct TLS | cert+key | https://host:3000 | Self-signed or internal CA | | Reverse proxy | None | MCP_ISSUER_URL=https://public-url | nginx/traefik handles TLS |

Docker Deployment

# docker-compose.yml
services:
  redmine-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - REDMINE_URL=https://your-redmine.example.com
      - MCP_HOST=0.0.0.0
      - MCP_PORT=3000
      - MCP_DATA_DIR=/data
      - MCP_TLS_CERT=/certs/server.crt
      - MCP_TLS_KEY=/certs/server.key
    volumes:
      - mcp-data:/data
      - ./certs:/certs:ro

volumes:
  mcp-data:

# Generate certificates
mkdir -p certs
openssl req -x509 -newkey rsa:2048 -keyout certs/server.key -out certs/server.crt \
  -days 365 -nodes -subj "/CN=your-server"

# Start
docker compose up -d

# Connect
claude mcp add redmine https://your-server:3000/mcp

Health check

curl -k https://localhost:3000/health
# => {"status":"ok","sessions":0}

Endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /mcp | JSON-RPC message handling (Bearer auth) | | GET | /mcp | SSE stream (Bearer auth) | | DELETE | /mcp | Session termination (Bearer auth) | | GET | /health | Health check (no auth) | | GET | /.well-known/oauth-authorization-server | OAuth metadata | | GET | /.well-known/oauth-protected-resource | Protected resource metadata | | POST | /authorize | OAuth authorization (renders API Key form) | | POST | /authorize/callback | API Key form submission | | POST | /token | Token exchange / refresh | | POST | /register | Dynamic client registration | | POST | /revoke | Token revocation |

Usage with VS Code

Using Cline (Claude Dev) extension

Install the Cline extension from VS Code marketplace
Open VS Code settings (Cmd/Ctrl + ,)
Search for "Cline MCP"
Add the Redmine server configuration:

{
  "cline.mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@flor3z-github/mcp-server-redmine"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using other MCP-compatible extensions

Check the extension's documentation for MCP server configuration. The pattern is typically similar to the above.

Usage with Zed Editor

Add to your Zed settings (~/.config/zed/settings.json):

{
  "context_servers": {
    "redmine": {
      "command": {
        "path": "npx",
        "args": ["-y", "@flor3z-github/mcp-server-redmine"],
        "env": {
          "REDMINE_URL": "https://your-redmine-instance.com",
          "REDMINE_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

Available Tools

Issue Tools

redmine_list_issues - List issues with filters
redmine_get_issue - Get issue details
redmine_create_issue - Create new issue
redmine_update_issue - Update existing issue
redmine_delete_issue - Delete issue

Project Tools

redmine_list_projects - List all projects
redmine_get_project - Get project details
redmine_get_project_versions - Get project versions

Time Entry Tools

redmine_list_time_entries - List time entries
redmine_get_time_entry - Get time entry details
redmine_create_time_entry - Create time entry
redmine_update_time_entry - Update time entry
redmine_delete_time_entry - Delete time entry
redmine_list_time_entry_activities - List activities

Wiki Tools

redmine_list_wiki_pages - List wiki pages
redmine_get_wiki_page - Get wiki page content
redmine_create_or_update_wiki_page - Create/update wiki page
redmine_delete_wiki_page - Delete wiki page

Journal Tools

redmine_update_journal - Update journal notes

Attachment Tools

redmine_get_attachment - Get attachment details
redmine_update_attachment - Update attachment metadata
redmine_delete_attachment - Delete attachment

File Tools

redmine_list_files - List project files
redmine_create_file - Attach uploaded file to project
redmine_upload_file - Upload file to Redmine

Utility Tools

redmine_list_statuses - List issue statuses
redmine_list_priorities - List issue priorities
redmine_list_trackers - List issue trackers
redmine_custom_request - Make custom API request
redmine_search - Search issues, wiki pages, and more

Example Queries

Once configured, you can ask your AI assistant questions like:

"Show me all open issues assigned to me"
"Create a new bug report for the API project"
"Log 2 hours of work on issue #123 for today"
"List all projects I have access to"
"Show me the wiki page about deployment procedures"
"What issues were updated this week?"
"Update issue #456 to set priority to high"
"Upload this file and attach it to issue #789"

Development

Running locally

# Install dependencies
npm install

# Run in development mode (stdio)
npm run dev

# Run in development mode (HTTP)
npm run dev:http

# Run tests
npm test

# Build for production
npm run build

Debugging with MCP Inspector

npm run inspector

This will start the MCP Inspector on http://localhost:5173

Security Considerations

Always use HTTPS for your Redmine URL
Store API keys securely and never commit them to version control
Use environment variables for sensitive configuration
Consider using read-only API keys when write access isn't needed
Implement proper SSL certificate validation in production
For HTTP transport, use TLS (MCP_TLS_CERT/MCP_TLS_KEY) to protect OAuth tokens and API keys in transit
OAuth tokens are persisted in MCP_DATA_DIR — ensure proper file permissions on the data directory

Troubleshooting

Connection Issues

Verify your Redmine URL is accessible
Check that the API is enabled in Redmine settings
Ensure your API key has the necessary permissions

Authentication Errors (Stdio)

Confirm your API key is valid and active
If using basic auth, verify username and password
Check that your user account is active

Authentication Errors (HTTP / OAuth)

If the browser auth page shows "API Key is invalid", verify the key in Redmine → My account → API access key
If the client receives 401, the access token may have expired — the client should automatically refresh via the refresh token
Check that MCP_DATA_DIR is writable by the server process
For reverse proxy setups, ensure MCP_ISSUER_URL matches the public URL the client uses

SSL/TLS Issues

For self-signed certificates, set REDMINE_SSL_VERIFY=false (not recommended for production)
Provide the CA certificate path via REDMINE_CA_CERT
For self-signed MCP server TLS certs, clients may need to trust the CA or use NODE_EXTRA_CA_CERTS

Development & Release

Branch Strategy

This project uses Git Flow with two main branches:

main - Production-ready code, triggers releases
develop - Integration branch for features (default branch)

Release Process

To create a release:

# 1. Ensure you're on develop with latest changes
git checkout develop
git pull origin develop

# 2. Bump version in package.json
npm version patch  # or minor, major

# 3. Push and create PR to main
git push origin develop
gh pr create --base main --head develop --title "Release vX.X.X"

# 4. Merge PR to trigger automated release

When the PR is merged to main, CI/CD automatically publishes to npm registry.

CI/CD Pipeline

GitHub Actions automatically:

Runs tests on Node.js 20.x, 22.x, and 24.x
Checks linting and builds
Auto-publishes to npm when merged to main
Uploads test coverage reports

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.