redmine-mcp-tools

v1.0.1

Published

3 months ago

A comprehensive Model Context Protocol (MCP) server for Redmine integration. Provides 25+ specialized tools for complete Redmine API access including issue management, project administration, time tracking, and user management. Built with TypeScript and d

Redmine MCP Tools

A comprehensive Model Context Protocol (MCP) server for Redmine integration, providing seamless access to Redmine's REST API through 25+ specialized tools. Built with TypeScript and designed for optimal performance and developer experience.

🚀 Quick Start

# Install globally
npm install -g redmine-mcp-tools

# Or use with npx (no installation required)
npx redmine-mcp-tools

📋 Table of Contents

✨ Features

This MCP server provides complete Redmine functionality through the following tool categories:

🎯 Issue Management (7 tools)

list_issues - List and search issues with flexible filtering options
get_issue - Get detailed information about a specific issue including custom fields
create_issue - Create new issues with full metadata support
update_issue - Update existing issues with validation
delete_issue - Safely delete issues with proper authorization
add_issue_watcher - Add watchers to issues for notifications
remove_issue_watcher - Remove watchers from issues

📁 Project Management (8 tools)

list_projects - List projects with optional filtering and pagination
show_project - Get detailed project information including modules and trackers
create_project - Create new projects with proper hierarchy setup
update_project - Update existing project configurations
archive_project - Archive projects while preserving data integrity
unarchive_project - Restore archived projects
delete_project - Permanently delete projects with safeguards
list_project_statuses - List all available project status options

⏱️ Time Entry Management (6 tools)

list_time_entries - List time entries with comprehensive filtering
show_time_entry - Get detailed time entry information
create_time_entry_for_project - Log time directly to projects with activity tracking
create_time_entry_for_issue - Log time to specific issues with detailed comments
update_time_entry - Modify existing time entries with audit trail
delete_time_entry - Remove time entries with proper validation

👥 User Management (5 tools)

list_users - List users with advanced filtering and search capabilities
show_user - Get comprehensive user profile information
create_user - Create new user accounts with role assignment
update_user - Update user profiles and permissions
delete_user - Deactivate or remove user accounts safely

🔧 Core Features

Type-safe API - Full TypeScript support with comprehensive type definitions
Error handling - Robust error management with detailed error messages
Authentication - Secure API key-based authentication
Validation - Input validation using Zod schemas
Flexible configuration - Environment-based configuration management
Comprehensive logging - Detailed logging for debugging and monitoring

📦 Installation

Prerequisites

Node.js 18 or higher
Redmine instance with REST API enabled
API access - Valid Redmine API key with appropriate permissions

Install Options

Option 1: Global Installation (Recommended)

npm install -g redmine-mcp-tools

Option 2: Use with npx (No installation required)

npx redmine-mcp-tools

Option 3: Local Installation

npm install redmine-mcp-tools

Option 4: From Source

git clone https://github.com/abdullahMASHUK/redmine-mcp-tools.git
cd redmine-mcp-tools
npm install
npm run build

⚙️ Configuration

Environment Variables

Configure the following environment variables for your Redmine instance:

# Required: Redmine server URL
export REDMINE_URL="https://your-redmine-instance.com"

# Required: Your Redmine API token
export USER_API_TOKEN="your_api_token_here"

Alternative Environment Variable Names

The server also supports these alternative variable names for flexibility:

# Alternative names (case-insensitive)
export redmine_url="https://your-redmine-instance.com"
export user_api_token="your_api_token_here"

Getting Your API Token

Log into your Redmine instance
Go to My Account → API access key
Click Show to reveal your API key
Copy the token for use in configuration

🚀 Usage

As a standalone MCP server

If installed globally

redmine-mcp-tools

If installed locally or using npx

npx redmine-mcp-tools

From source

npm start

Integration with MCP-compatible applications

Option 1: Using npx (Recommended)

Add to your MCP client configuration:

{
  "mcpServers": {
    "redmine-connector": {
      "command": "npx",
      "args": ["redmine-mcp-tools"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "USER_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Option 2: Using global installation

{
  "mcpServers": {
    "redmine-connector": {
      "command": "redmine-mcp-tools",
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "USER_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Option 3: Using local installation

{
  "mcpServers": {
    "redmine-connector": {
      "command": "node",
      "args": ["./node_modules/redmine-mcp-tools/dist/index.js"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "USER_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

🛠️ API Tools

Complete Tool Reference

| Category | Tool Name | Description | |----------|-----------|-------------| | Issues | list_issues | List and filter issues with advanced search | | | get_issue | Retrieve detailed issue information | | | create_issue | Create new issues with metadata | | | update_issue | Update existing issue properties | | | delete_issue | Delete issues safely | | | add_issue_watcher | Add watchers to issues | | | remove_issue_watcher | Remove watchers from issues | | Projects | list_projects | List projects with filtering | | | show_project | Get detailed project information | | | create_project | Create new projects | | | update_project | Update project configurations | | | archive_project | Archive projects | | | unarchive_project | Restore archived projects | | | delete_project | Delete projects permanently | | | list_project_statuses | List project status options | | Time Entries | list_time_entries | List time entries with filters | | | show_time_entry | Get time entry details | | | create_time_entry_for_project | Log time to projects | | | create_time_entry_for_issue | Log time to issues | | | update_time_entry | Update time entries | | | delete_time_entry | Delete time entries | | Users | list_users | List users with search | | | show_user | Get user profile details | | | create_user | Create new user accounts | | | update_user | Update user information | | | delete_user | Deactivate user accounts |

📚 Examples

Basic Operations

List recent issues

{
  "tool": "list_issues",
  "arguments": {
    "limit": 10,
    "sort": "updated_on:desc",
    "status_id": "open"
  }
}

Create a new issue

{
  "tool": "create_issue", 
  "arguments": {
    "project_id": 1,
    "subject": "Implement new feature",
    "description": "Detailed description of the feature request",
    "tracker_id": 2,
    "priority_id": 3,
    "assigned_to_id": 5
  }
}

Update an existing issue

{
  "tool": "update_issue",
  "arguments": {
    "issue_id": 123,
    "status_id": 3,
    "notes": "Work completed and ready for review"
  }
}

Time Tracking

Log time to an issue

{
  "tool": "create_time_entry_for_issue",
  "arguments": {
    "issue_id": 123,
    "hours": 2.5,
    "activity_id": 8,
    "spent_on": "2025-01-15",
    "comments": "Implemented feature and added tests"
  }
}

Log time to a project

{
  "tool": "create_time_entry_for_project",
  "arguments": {
    "project_id": 1,
    "hours": 4,
    "activity_id": 9,
    "spent_on": "2025-01-15",
    "comments": "Project planning and architecture review"
  }
}

Project Management

Create a new project

{
  "tool": "create_project",
  "arguments": {
    "name": "New Project",
    "identifier": "new-project",
    "description": "Project description",
    "is_public": false,
    "parent_id": 1
  }
}

User Management

List active users

{
  "tool": "list_users",
  "arguments": {
    "status": 1,
    "limit": 50
  }
}

🔧 Development

Development Setup

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

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your Redmine configuration

# Development mode with auto-reload
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Build TypeScript
npm run build

# Run built version
npm start

Project Structure

redmine-mcp-tools/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── handlers/             # Request handlers
│   │   ├── issues.ts         # Issue management handlers
│   │   ├── projects.ts       # Project management handlers
│   │   ├── time_entries.ts   # Time tracking handlers
│   │   └── users.ts          # User management handlers
│   ├── tools/                # Tool definitions
│   ├── lib/                  # Core utilities
│   │   ├── client.ts         # Redmine API client
│   │   └── config.ts         # Configuration management
│   └── types/                # TypeScript type definitions
├── dist/                     # Compiled JavaScript
├── tests/                    # Test files
└── docs/                     # Documentation

📖 API Reference

All tools follow Redmine's REST API conventions. For detailed parameter information, refer to:

Authentication

This server uses API key authentication. Ensure your API key has the necessary permissions for the operations you want to perform.

Error Handling

The server provides comprehensive error handling with detailed error messages for:

Authentication failures
Permission issues
Invalid parameters
Network connectivity problems
Redmine server errors

🤝 Contributing

We welcome contributions! Here's how you can help:

Getting Started

Fork the repository on GitHub
Clone your fork locally
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with proper documentation
Add tests for new functionality
Run the test suite (npm test)
Commit your changes (git commit -m 'Add amazing feature')
Push to your branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Code Style: Follow the existing TypeScript/ESLint configuration
Testing: Add unit tests for new features and bug fixes
Documentation: Update README and inline documentation
Type Safety: Maintain full TypeScript coverage
API Compatibility: Ensure backward compatibility

Reporting Issues

When reporting issues, please include:

Environment details (Node.js version, OS, Redmine version)
Steps to reproduce the issue
Expected vs actual behavior
Error messages or logs
Configuration details (without sensitive information)

📄 License

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

🔗 Links

npm Package: redmine-mcp-tools
GitHub Repository: abdullahMASHUK/redmine-mcp-tools
Issue Tracker: GitHub Issues
Redmine Documentation: Redmine REST API
Model Context Protocol: MCP Documentation

📞 Support

Need help? Here are your options:

Documentation

README: This document covers most common use cases
API Reference: Check the Redmine REST API documentation
Examples: See the examples section above for common patterns

Troubleshooting

Check your configuration: Verify REDMINE_URL and USER_API_TOKEN
Verify API permissions: Ensure your API key has sufficient permissions
Test connectivity: Try accessing your Redmine instance directly
Check logs: Enable debug logging for detailed error information

Getting Help

GitHub Issues: Report bugs or request features
Discussions: Community discussions and Q&A

Made with ❤️ by abdullahMASHUK