Redmine MCP Service Adapter

This software package implements the Model Context Protocol (MCP) server specifications, providing an interface to interact with the Redmine project management system through its underlying Representational State Transfer (REST) Application Programming Interface (API). It furnishes Large Language Models (LLMs) with granular access to project artifacts and metadata.

Core Capabilities

Capability to interact with stable endpoints provided by the Redmine REST API:

• Ticketing System Records (Issues) (v1.0 and later)
• Project Hierarchies (v1.0 and later)
• Personnel Directory (Users) (v1.1 and later)
• Effort Logging (Time Entries) (v1.1 and later)

Functional Toolset

Ticket Management (Issues)

• Query Issues: Execute searches based on criteria such as associated project, current state, assigned personnel, and textual content.
• Advanced filtering mechanisms.
• Full-text search capabilities.
• Support for extending parameters via custom fields.
• Provision/Modify Issues: Operations for creation and modification.
• Specification of ticket type (tracker), lifecycle status, and urgency.
• Configuration of dynamic custom fields.
• Augmentation with narrative commentary.
• Retire Issues: Permanent removal of a ticket record.

Project Registry

• Enumerate Projects: Locate projects based on their lifecycle status (active, dormant, finalized) and descriptive nomenclature.
• Retrieve Project Metadata: Fetch detailed attributes, including associated issue trackers and categorization schemes.
• Provision/Modify Projects: Establish new project structures or alter existing ones.
• Define supported modules and mandated issue types.
• Configure member propagation rules.
• Toggle Project Status: Move projects between active and archived/closed states.
• Remove Projects: Delete project definitions.

Effort Tracking (Time Entries)

• Query Time Logs: Search logged activities filtered by project grouping, personnel responsible, and temporal boundaries.
• Fetch Time Entry Details
• Provision/Modify Time Logs: Record effort expenditures.
• Link effort to a specific project or individual issue.
• Define the nature of the activity performed.
• Apply custom metadata tags.
• Delete Time Entries

Integration Guide for Claude

Deployment with the Claude AI system requires the following execution configuration:

{ "mcp-server-redmine": { "command": "npx", "args": [ "-y", "--prefix", "/path/to/mcp-server-redmine", "mcp-server-redmine" ], "env": { "REDMINE_HOST": "https://your-redmine.example.com", "REDMINE_API_KEY": "your-api-key-here" } } }

Configuration Parameters

• command: Invocation mechanism for the Node Package Manager (npm) artifact.
• args:
• -y: Automates affirmative responses to interactive prompts.
• --prefix: Designates the local directory for tool installation.
• The final element specifies the server package identifier.
• env: Necessary operational environmental settings
• REDMINE_HOST: The Uniform Resource Locator (URL) pointing to the Redmine instance.
• REDMINE_API_KEY: The secret authentication token for API access.

Initialization Sequence

API Token Acquisition

1. Navigate to Redmine system administration settings and enable the web service API.
2. Secure the unique API token from the authenticated user's personal settings panel.

Environment Variables Configuration

Establish the following variables in the execution environment:

• REDMINE_API_KEY: The security token retrieved from Redmine user profile settings.
• REDMINE_HOST: The root address of the Redmine installation (e.g., https://redmine.example.com).

Validation Procedures

Component Testing

bash

Execute unit validation suites

npm test

Note: Tests are deliberately restricted to safe, read-only (GET) operations to preserve data integrity.

Protocol Inspector Validation

Use the MCP Inspector Utility to confirm operational readiness.

Graphical User Interface (GUI) Mode

bash

Compile the source code

npm run build

Ensure execution rights are set (critical step)

chmod +x dist/index.js

Initiate the inspector interface

npx @modelcontextprotocol/inspector dist/index.js

Command Line Interface (CLI) Mode

CLI Testing Scenarios

Prerequisites:

bash

Build compilation

npm run build

Set execution permissions

chmod +x dist/index.js

Set necessary runtime environment variables

export REDMINE_API_KEY=your-api-key-here export REDMINE_HOST=http://localhost:3000 # Adjust as necessary

Basic Interaction Commands:

1. Inventory of available functions:

bash npx @modelcontextprotocol/inspector --cli \ -e REDMINE_API_KEY=$REDMINE_API_KEY \ -e REDMINE_HOST=$REDMINE_HOST \ node dist/index.js \ --method tools/list

1. Validating Issue Operations:

bash # Retrieve a limited set of tickets npx @modelcontextprotocol/inspector --cli \ -e REDMINE_API_KEY=$REDMINE_API_KEY \ -e REDMINE_HOST=$REDMINE_HOST \ node dist/index.js \ --method tools/call \ --tool-name list_issues \ --tool-arg limit=5

# Fetch metadata for a specific ticket ID npx @modelcontextprotocol/inspector --cli \ -e REDMINE_API_KEY=$REDMINE_API_KEY \ -e REDMINE_HOST=$REDMINE_HOST \ node dist/index.js \ --method tools/call \ --tool-name get_issue \ --tool-arg id=1

# Constrain ticket search by project context npx @modelcontextprotocol/inspector --cli \ -e REDMINE_API_KEY=$REDMINE_API_KEY \ -e REDMINE_HOST=$REDMINE_HOST \ node dist/index.js \ --method tools/call \ --tool-name list_issues \ --tool-arg project_id=1 \ --tool-arg limit=3

1. Validating Project Operations:

bash # Fetch the complete registry of projects npx @modelcontextprotocol/inspector --cli \ -e REDMINE_API_KEY=$REDMINE_API_KEY \ -e REDMINE_HOST=$REDMINE_HOST \ node dist/index.js \ --method tools/call \ --tool-name list_projects

# Inspect details of a singular project npx @modelcontextprotocol/inspector --cli \ -e REDMINE_API_KEY=$REDMINE_API_KEY \ -e REDMINE_HOST=$REDMINE_HOST \ node dist/index.js \ --method tools/call \ --tool-name show_project \ --tool-arg id=1

1. Validating User Directory Access (Requires elevated credentials):

bash # List all registered system users npx @modelcontextprotocol/inspector --cli \ -e REDMINE_API_KEY=$REDMINE_API_KEY \ -e REDMINE_HOST=$REDMINE_HOST \ node dist/index.js \ --method tools/call \ --tool-name list_users

# Retrieve profile data for a specific user ID npx @modelcontextprotocol/inspector --cli \ -e REDMINE_API_KEY=$REDMINE_API_KEY \ -e REDMINE_HOST=$REDMINE_HOST \ node dist/index.js \ --method tools/call \ --tool-name show_user \ --tool-arg id=1

1. Validating Time Log Operations:

bash # Retrieve a subset of recorded time logs npx @modelcontextprotocol/inspector --cli \ -e REDMINE_API_KEY=$REDMINE_API_KEY \ -e REDMINE_HOST=$REDMINE_HOST \ node dist/index.js \ --method tools/call \ --tool-name list_time_entries \ --tool-arg limit=5

# Fetch specific time entry record details npx @modelcontextprotocol/inspector --cli \ -e REDMINE_API_KEY=$REDMINE_API_KEY \ -e REDMINE_HOST=$REDMINE_HOST \ node dist/index.js \ --method tools/call \ --tool-name show_time_entry \ --tool-arg id=1

Advanced Query Examples:

bash

Filter issue retrieval by predefined status code

npx @modelcontextprotocol/inspector --cli \ -e REDMINE_API_KEY=$REDMINE_API_KEY \ -e REDMINE_HOST=$REDMINE_HOST \ node dist/index.js \ --method tools/call \ --tool-name list_issues \ --tool-arg status_id=1 \ --tool-arg limit=5

Search issues matching keywords in the summary field

npx @modelcontextprotocol/inspector --cli \ -e REDMINE_API_KEY=$REDMINE_API_KEY \ -e REDMINE_HOST=$REDMINE_HOST \ node dist/index.js \ --method tools/call \ --tool-name list_issues \ --tool-arg subject="defect report" \ --tool-arg limit=3

Isolate time consumption records for a specific project identifier

npx @modelcontextprotocol/inspector --cli \ -e REDMINE_API_KEY=$REDMINE_API_KEY \ -e REDMINE_HOST=$REDMINE_HOST \ node dist/index.js \ --method tools/call \ --tool-name list_time_entries \ --tool-arg project_id=1 \ --tool-arg limit=10

Troubleshooting Guide:

• Connectivity Failures: Validate network accessibility and server responsiveness:

bash curl -H "X-Redmine-API-Key: $REDMINE_API_KEY" \ "$REDMINE_HOST/projects.json"

• Authorization Failures: Confirm that the API token possesses the requisite permissions for the requested action within the Redmine security configuration.

• Environment Variable Integrity: Verify that necessary variables are correctly exported:

bash echo $REDMINE_API_KEY echo $REDMINE_HOST

• Compilation Status Check: Ensure all required build steps are complete: bash npm run build chmod +x dist/index.js ls -la dist/index.js

Required Privileges

Specific system interactions necessitate elevated administrative authority:

User Account Operations

• list_users: Administrative clearance mandatory.
• create_user: Administrative clearance mandatory.
• update_user: Administrative clearance mandatory.
• delete_user: Administrative clearance mandatory.

Data visibility is contingent upon the invoking principal's authorization level. Consult the Redmine API Documentation for granular detail.

Engineering and Maintenance

Prerequisites

• Runtime Environment: Node.js version 18 or greater.
• Package Manager: npm version 9 or greater.

Dependency Stack

• @modelcontextprotocol/sdk: The core framework for protocol interaction.
• zod: Utility for robust schema validation.
• typescript: Programming language compiler.

Source Code Layout

. ├── src/ │ ├── tools/ # Tool definitions and method implementations │ │ ├── issues.ts │ │ ├── projects.ts │ │ ├── time_entries.ts │ │ └── index.ts │ ├── formatters/ # Output data transformation modules │ │ ├── issues.ts │ │ ├── projects.ts │ │ ├── time_entries.ts │ │ └── index.ts │ ├── lib/ # Shared utilities and core components │ │ ├── client.ts # Redmine API communication layer │ │ ├── config.ts # Runtime configuration loading │ │ └── types.ts # Shared type/interface declarations │ ├── handlers.ts # Request processing entry points │ └── index.ts # Primary application bootstrap file ├── docs/ │ └── adr/ # Archival repository for design rationales ├── package.json # Project metadata and dependency listing ├── tsconfig.json # TypeScript compiler directives └── README.md # Primary documentation file

Build Workflow

bash

Install all necessary packages

npm install

Compile TypeScript into JavaScript output

npm run build

Initiate local development instance (if applicable)

npm run dev

Architectural Documentation

Key architectural determinations are preserved within the docs/adr directory structure. Review these records prior to undertaking substantial feature additions or structural modifications.

Licensing

Distributed under the MIT License.

Associated Ecosystem Projects

• Model Context Protocol
• MCP TypeScript SDK
• Redmine Project Management System

WIKIPEDIA: Tools designed for enterprise administration encompass a wide array of systems, applications, controls, calculation engines, and methodologies employed by commercial entities to navigate evolving market dynamics, secure a competitive market placement, and enhance operational efficacy.

== General Context == Management utilities can be segmented based on organizational function, covering domains like operational scheduling, workflow management, record maintenance, human resource oversight, strategic determination, performance measurement, and so forth. A functional taxonomy often includes:

Utilities for data acquisition and validation across all organizational units. Systems dedicated to monitoring and optimizing core business procedures. Platforms for aggregating data to support high-level decision-making. Contemporary management technologies have undergone rapid transformation in the past decade, propelled by swift technological progression, making optimal tool selection a complex challenge for any organization seeking cost reduction, revenue growth, deeper customer understanding, or improved product fulfillment aligned with client expectations. In this environment, leadership should adopt a strategic framework for governance software selection, adapting the chosen instruments to organizational mandates rather than passively adopting the newest available solution. Careful evaluation and subsequent tailored customization of business tools are essential for achieving systemic stability.

== Global Adoption Statistics == Data from a 2013 survey by Bain & Company illustrated the global utilization patterns of business technologies, reflecting regional imperatives shaped by economic conditions. The leading ten documented approaches included:

Strategic planning frameworks Client relationship management systems (CRM) Staff sentiment evaluation processes Competitive assessment (Benchmarking) Key performance indicator aggregation (Balanced Scorecard) Identification of unique organizational strengths (Core competency) External resource allocation (Outsourcing) Programmes for organizational transition (Change management) Logistics and resource distribution oversight (Supply chain management) Formal articulation of organizational purpose (Mission/Vision statements) Customer base segmentation methodologies Comprehensive quality assurance protocols (Total Quality Management)

== Commercial Software Applications == Software suites or discrete computational programs utilized by professional staff to execute various corporate functions are termed business software. These applications are designed to augment productivity, quantify output metrics, and execute diverse corporate tasks with precision. The technological lineage stretches from early Management Information Systems (MIS) through Enterprise Resource Planning (ERP) systems, later incorporating Customer Relationship Management (CRM) capabilities, culminating in the current domain of cloud-based enterprise management solutions. While a quantifiable link exists between IT investment and organizational prosperity, value maximization hinges on two factors: the proficiency of deployment and the diligence in selecting and customizing the appropriate technological assets.

== Resources for Small and Medium Enterprises (SMEs) == Tools specifically engineered for SMEs are vital as they provide avenues for efficiency gains and resource optimization...