Redmine MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to Redmine project management software via its REST API.

Features

Full Redmine API Access: Interact with projects, issues, users, time entries, and more
MCP Protocol: Standard protocol for AI-to-tool communication
Standalone Server: Independent deployment, connects to any Redmine instance
Secure: API key-based authentication with Redmine
Flexible: Configurable via environment variables

Prerequisites

Ruby 3.1 or higher
Access to a Redmine instance (5.0+) with REST API enabled
Redmine API key (obtain from /my/account page in Redmine)

Optional Redmine Plugins

Some MCP tools require the Redmine Extended API plugin for advanced functionality:

Custom Fields CRUD: create_custom_field, update_custom_field, delete_custom_field
Queries CRUD: create_query, update_query, delete_query
Bulk Time Entries: bulk_create_time_entries

Installation:

cd /path/to/redmine/plugins
git clone https://github.com/zh/redmine_extended_api.git
cd /path/to/redmine
bundle install
bundle exec rake redmine:plugins:migrate RAILS_ENV=production
systemctl restart redmine

See redmine_extended_api for details.

Note: All other MCP tools work with standard Redmine REST API (no plugins required).

Installation

Clone or download this repository
Install dependencies:
```
bundle install
```
Copy the example environment file and configure:
```
cp .env.example .env
```

Edit .env and set your Redmine credentials:

REDMINE_URL=https://your-redmine-instance.com
REDMINE_API_KEY=your_api_key_here

Configuration

All configuration is done via environment variables in the .env file:

Required Configuration

Variable	Description	Default	Required
`REDMINE_URL`	Base URL of your Redmine instance	-	Yes
`REDMINE_API_KEY`	Your Redmine API key	-	Yes

Server Configuration

Variable	Description	Default	Required
`MCP_PORT`	Port for the MCP server	3100	No
`MCP_HOST`	Host to bind to	localhost	No
`RACK_ENV`	Environment (development/production)	development	No
`LOG_LEVEL`	Logging level (debug/info/warn/error)	info	No

Performance Configuration

Variable	Description	Default	Required
`HTTP_TIMEOUT`	HTTP request timeout in seconds	30	No
`HTTP_READ_TIMEOUT`	HTTP read timeout in seconds	60	No
`FALCON_PROCESSES`	Number of server worker processes	1	No
`METRICS_SLOW_THRESHOLD`	Slow request threshold in seconds	1.0	No

Note: Connection pooling and compression (gzip/deflate) are handled automatically by the async HTTP client.

Getting Your Redmine API Key

Log into your Redmine instance
Navigate to "My Account" (/my/account)
Look for "API access key" on the right sidebar
Click "Show" to reveal your key, or "Reset" to generate a new one
Copy the key to your .env file

Usage

Starting the Server

The server uses Falcon, a high-performance async web server.

Development mode (with auto-reload):

bundle exec rerun -- falcon serve --bind http://localhost:3100

Production mode:

bundle exec falcon serve --bind http://localhost:3100

The server will start with multiple worker processes (8 by default) for optimal performance. You can control the number of workers by setting FALCON_PROCESSES in your .env file.

Connecting from MCP Clients

Add the server to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "redmine": {
      "command": "bundle",
      "args": ["exec", "falcon", "serve", "--bind", "http://localhost:3100"],
      "cwd": "/path/to/redmine_mcp_server"
    }
  }
}

Or connect to the running server:

{
  "mcpServers": {
    "redmine": {
      "url": "http://localhost:3100/mcp"
    }
  }
}

Available Tools

Current Status

53 Fully Implemented Tools (Projects, Memberships, Versions, Issues, Users, Groups, Time Entries, Custom Fields, Queries, Batch Operations)
21 Skeleton Tools (structure defined, ready for implementation)
74 Total Tools across 14 resource categories

Implemented Tools ✅

Project Operations (5 tools)

list_projects - List all accessible projects with pagination and filtering
get_project - Get detailed information about a specific project
create_project - Create a new project
update_project - Update an existing project
delete_project - Delete a project

Membership Operations (5 tools)

list_memberships - List all members of a project
get_membership - Get details of a specific membership
create_membership - Add a user/group to a project with roles
update_membership - Update roles for a project member
delete_membership - Remove a user/group from a project

Version/Milestone Operations (5 tools)

list_versions - List versions/milestones for a project
get_version - Get details of a specific version
create_version - Create a new version/milestone
update_version - Update an existing version
delete_version - Delete a version

Issue Operations (13 tools)

list_issues - List issues with filtering, sorting, and pagination (supports query_id for saved queries)
get_issue - Get detailed information about a specific issue
create_issue - Create a new issue in a project
update_issue - Update an existing issue
delete_issue - Delete an issue
add_issue_watcher - Add a watcher to an issue
remove_issue_watcher - Remove a watcher from an issue
get_issue_relations - Get all relations for an issue (blocks, relates to, etc.)
create_issue_relation - Create a relation between two issues
delete_issue_relation - Delete an issue relation
get_issue_journals - Get the change history (journals) for an issue
copy_issue - Copy an issue to another project or within the same project
move_issue - Move an issue to a different project

User Operations (5 tools)

list_users - List all users with filtering and pagination
get_user - Get detailed information about a specific user
create_user - Create a new user account (requires admin)
update_user - Update an existing user account
delete_user - Delete a user account

Group Operations (5 tools)

list_groups - List all groups (requires admin)
get_group - Get details of a specific group including members
create_group - Create a new group with optional initial members
update_group - Update group details and membership
delete_group - Delete a group

Time Entry Operations (6 tools)

list_time_entries - List time entries with filtering by user, project, issue, or date range
get_time_entry - Get detailed information about a specific time entry
create_time_entry - Log time on an issue or project
update_time_entry - Update an existing time entry
delete_time_entry - Delete a time entry
bulk_create_time_entries - Create multiple time entries in a single request (requires Extended API plugin)

Custom Field Operations (4 tools)

list_custom_fields - List all custom fields with their configuration
create_custom_field - Create a new custom field (requires admin, Extended API plugin)
update_custom_field - Update an existing custom field (requires admin, Extended API plugin)
delete_custom_field - Delete a custom field (requires admin, Extended API plugin)

Note: Custom field values can be set in issues, projects, users, and other entities using the custom_field_values or custom_fields parameter in their respective create/update tools.

Query Operations (4 tools)

list_queries - List all accessible queries (saved filters) with pagination
create_query - Create a new query with filters, visibility, and columns (requires Extended API plugin)
update_query - Update an existing query (requires Extended API plugin)
delete_query - Delete a query (requires Extended API plugin)

Query Features:

Saved Filters: Queries are saved filters for issues, time entries, projects, etc.
Filter Operators: Supports all Redmine operators (=, !=, >=, <=, ~, !~, o (open), c (closed), t (today), w (week), m (month), <t+N, >t-N)
Visibility Levels: Private (0), Roles (1), Public (2)
Query Types: IssueQuery, ProjectQuery, TimeEntryQuery
Execution: Use list_issues with query_id parameter to execute saved queries
Permissions: Users manage own private queries; manage_public_queries for project queries; admin for global queries

Example - Create and execute a query:

// 1. Create a query for late issues
{
  "name": "create_query",
  "params": {
    "name": "Late Issues Before May",
    "type": "IssueQuery",
    "visibility": 0,
    "filters": {
      "due_date": {"operator": "<=", "values": ["2025-05-01"]},
      "status_id": {"operator": "o"}
    },
    "column_names": ["id", "subject", "status", "due_date"],
    "sort_criteria": [["due_date", "asc"]]
  }
}
// Returns: {"id": 10, "name": "Late Issues Before May", ...}

// 2. Execute the saved query
{
  "name": "list_issues",
  "params": {
    "query_id": 10
  }
}
// Returns filtered and sorted issues based on the saved query

Batch Operations (1 tool)

batch_execute - Execute multiple MCP tools concurrently for improved performance

Skeleton Tools (Ready for Implementation) ⏳

All skeleton tools are defined with complete schemas but raise NotImplementedError:

Wiki Pages (6 tools): list, get, create, update, delete, versions
Attachments (3 tools): upload, get, delete
News (2 tools): list, get
Reference Data (7 tools): trackers, statuses, priorities, activities, roles, search

See TOOLS.md for complete tool documentation.

Performance & Monitoring

The MCP server includes built-in performance optimizations and monitoring capabilities.

Performance Features

HTTP Optimizations (Async Architecture)

Automatic Connection Pooling: Async HTTP client manages connections automatically
HTTP Keep-Alive: Efficient connection reuse with automatic management
Response Compression: Automatic gzip/deflate compression (70-80% bandwidth reduction)
Fiber-Based Concurrency: Lightweight concurrent operations using Ruby fibers
Configurable Timeouts: Separate settings for connection and read operations
Multi-Process Server: Falcon runs multiple worker processes (configurable) for true parallelism

Batch Execution

Use the batch_execute tool to run multiple operations concurrently:

{
  "name": "batch_execute",
  "params": {
    "calls": [
      { "name": "get_issue", "params": { "id": 123 } },
      { "name": "get_issue", "params": { "id": 456 } },
      { "name": "list_time_entries", "params": { "issue_id": 123 } }
    ],
    "max_concurrency": 5
  }
}

Performance gain: Up to 20x faster for independent operations compared to sequential execution.

Metrics Endpoints

Monitor server performance in real-time:

Prometheus Format (for monitoring tools like Grafana):

curl http://localhost:3100/metrics

Tool Metrics (JSON):

curl http://localhost:3100/metrics/tools

Returns:

{
  "tools": [
    {
      "tool": "list_issues",
      "total_calls": 42,
      "success_count": 40,
      "error_count": 2,
      "total_duration_ms": 1250.5,
      "avg_duration_ms": 29.77,
      "errors_by_type": { "NotFoundError": 2 }
    }
  ]
}

API Metrics (JSON):

curl http://localhost:3100/metrics/api

Slow Requests (JSON):

curl http://localhost:3100/metrics/slow

Lists requests exceeding the slow threshold (default: 1.0 second).

Performance Configuration

Configure performance settings in .env:

# HTTP timeouts in seconds
HTTP_TIMEOUT=30          # Request timeout
HTTP_READ_TIMEOUT=60     # Read timeout

# Server configuration
FALCON_PROCESSES=1       # Number of worker processes (increase for production)

# Metrics
METRICS_SLOW_THRESHOLD=1.0  # Slow request threshold in seconds

Note: The async HTTP client handles connection pooling and compression automatically. No manual configuration needed for these features.

See docs/PERFORMANCE.md for detailed performance tuning guide.

Development

Running Tests

All implemented tools have comprehensive RSpec test coverage (330+ tests).

Run all tests:

bundle exec rspec

Run specific tool category:

bundle exec rspec spec/tools/time_entries/
bundle exec rspec spec/tools/custom_fields/
bundle exec rspec spec/tools/queries/

Test coverage includes:

Tool metadata validation
Success cases with minimum and optional parameters
Required parameter validation
Error handling (auth, validation, not found)

See TOOLS.md for detailed testing guide.

Code Quality

bundle exec rubocop
bundle exec rubocop --autocorrect

Project Structure

redmine_mcp_server/
├── lib/
│   ├── redmine_mcp_server.rb    # Main application
│   ├── async_redmine_client.rb  # Async Redmine API client
│   ├── tools/                    # MCP tools (operations)
│   │   ├── base_tool.rb
│   │   ├── projects/             # Project CRUD
│   │   ├── issues/               # Issue operations
│   │   └── ...
│   └── resources/                # MCP resources (data sources)
├── spec/                         # RSpec tests
├── Gemfile                       # Ruby dependencies
├── config.ru                     # Rack configuration
└── .env                          # Environment configuration

Architecture

┌─────────────┐         ┌──────────────────┐         ┌─────────────┐
│             │         │                  │         │             │
│  AI Client  │ ◄─MCP──►│  Redmine MCP     │ ◄─HTTP──►│  Redmine    │
│  (Claude)   │         │     Server       │         │   Instance  │
│             │         │                  │         │             │
└─────────────┘         └──────────────────┘         └─────────────┘

AI Client: Claude or other MCP-compatible AI assistant
Redmine MCP Server: This application (translates MCP to Redmine API)
Redmine Instance: Your Redmine installation

Troubleshooting

Connection Issues

Error: "Missing required environment variable: REDMINE_URL"

Make sure you have a .env file in the project root
Verify all required variables are set

Error: "Connection refused" or "Timeout"

Check that your REDMINE_URL is correct and accessible
Verify that Redmine's REST API is enabled (Administration → Settings → API)
Test API access manually: curl -H "X-Redmine-API-Key: YOUR_KEY" https://your-redmine.com/users/current.json

Error: "401 Unauthorized"

Verify your API key is correct
Check that the user associated with the API key has appropriate permissions
Generate a new API key if necessary

Server Issues

Error: "Address already in use"

Another process is using port 3100
Change the port in .env: MCP_PORT=3101
Or stop the other process: lsof -ti:3100 | xargs kill -9

Security Considerations

API Keys: Never commit .env files to version control
Network: In production, use HTTPS for Redmine connections
Firewall: Restrict MCP server access to trusted clients only
Permissions: Use Redmine API keys with appropriate permissions (principle of least privilege)

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Write tests for new functionality
Ensure all tests pass and code passes rubocop
Submit a pull request

License

This project is available for use under the MIT License.

Acknowledgments

Built with mcp_on_ruby
Powered by Redmine REST API
Uses Async for high-performance concurrent HTTP communication
Served by Falcon, a modern async web server

Support

For issues, questions, or contributions:

GitHub Issues: Create an issue
Documentation: Redmine REST API

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
bin		bin
docs		docs
lib		lib
spec		spec
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.rubocop.yml		.rubocop.yml
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE		LICENSE
README.md		README.md
TOOLS.md		TOOLS.md
config.ru		config.ru

License

zh/redmine_mcp_server

Folders and files

Latest commit

History

Repository files navigation

Redmine MCP Server

Features

Prerequisites

Optional Redmine Plugins

Installation

Configuration

Required Configuration

Server Configuration

Performance Configuration

Getting Your Redmine API Key

Usage

Starting the Server

Connecting from MCP Clients

Available Tools

Current Status

Implemented Tools ✅

Project Operations (5 tools)

Membership Operations (5 tools)

Version/Milestone Operations (5 tools)

Issue Operations (13 tools)

User Operations (5 tools)

Group Operations (5 tools)

Time Entry Operations (6 tools)

Custom Field Operations (4 tools)

Query Operations (4 tools)

Batch Operations (1 tool)

Skeleton Tools (Ready for Implementation) ⏳

Performance & Monitoring

Performance Features

HTTP Optimizations (Async Architecture)

Batch Execution

Metrics Endpoints

Performance Configuration

Development

Running Tests

Code Quality

Project Structure

Architecture

Troubleshooting

Connection Issues

Server Issues

Security Considerations

Contributing

License

Acknowledgments

Support

Roadmap

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages