redmine-mcp-server

unokun/redmine-mcp-server

3.2

If you are the rightful owner of redmine-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Redmine MCP Server is a Model Context Protocol server designed to integrate with Redmine project management systems, providing a standardized protocol interface for managing tickets and project information.

Tools
7
Resources
0
Prompts
0

Redmine MCP Server

A Model Context Protocol (MCP) server for integrating with Redmine project management systems. This server provides MCP tools for creating, updating, searching tickets, and managing project information in Redmine through a standardized protocol interface.

Features

  • Ticket Management: Create, update, search, and retrieve Redmine tickets
  • Project Information: List projects, get project details, and manage users
  • MCP Protocol Compliance: Full support for Model Context Protocol standard
  • Secure Configuration: Environment variables and configuration file support
  • Comprehensive Error Handling: Detailed error reporting and logging
  • Async Support: High-performance asynchronous operations

Installation

Prerequisites

  • Python 3.11 or higher
  • uv package manager
  • Access to a Redmine server with API enabled
  • Valid Redmine API key

Install uv (if not already installed)

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv

Install from PyPI (when published)

# Install globally using uvx
uvx redmine-mcp-server

# Or install in a project
uv add redmine-mcp-server

Install from Source

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

# Install dependencies
uv sync

# Install in development mode
uv pip install -e .

Configuration

The server supports two configuration methods: environment variables and configuration files.

Method 1: Environment Variables

  1. Copy the example environment file:

    cp .env.example .env

  2. Edit .env with your Redmine server details:

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

# Required: Redmine API key
REDMINE_API_KEY=your_api_key_here

# Optional: Log level (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

# Optional: Request timeout in seconds
REQUEST_TIMEOUT=30

Method 2: Configuration File

  1. Copy the example configuration file:

    cp config.example.json config.json

  2. Edit config.json with your settings:

    {
  "redmine": {
    "url": "https://your-redmine-server.com",
    "api_key": "your_api_key_here",
    "timeout": 30
  },
  "logging": {
    "level": "INFO",
    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
  },
  "mcp": {
    "server_name": "redmine-mcp-server",
    "version": "1.0.0"
  }
}

  3. Secure the configuration file:

    chmod 600 config.json

Getting Your Redmine API Key

  1. Log into your Redmine server
  2. Go to "My account" (usually in the top-right menu)
  3. Click on "API access key" in the right sidebar
  4. Click "Show" to reveal your API key
  5. Copy the key to your configuration

Usage

Running the Server

Using uvx (Recommended for MCP clients)
# Run directly with uvx
uvx redmine-mcp-server

# With configuration file
uvx redmine-mcp-server --config config.json

# With debug logging
uvx redmine-mcp-server --debug
Using uv run (Development)
# Using environment variables
uv run redmine-mcp-server

# Using configuration file
uv run redmine-mcp-server --config config.json

# Enable debug mode
uv run redmine-mcp-server --debug
Direct Python execution
# Using the module
uv run python -m redmine_mcp_server.main

# With arguments
uv run python -m redmine_mcp_server.main --config config.json --debug

MCP Client Configuration

Claude Desktop Configuration

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

{
  "mcpServers": {
    "redmine": {
      "command": "uvx",
      "args": ["redmine-mcp-server"],
      "env": {
        "REDMINE_URL": "https://your-redmine-server.com",
        "REDMINE_API_KEY": "your_api_key_here",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
Using Configuration File with MCP Client
{
  "mcpServers": {
    "redmine": {
      "command": "uvx",
      "args": ["redmine-mcp-server", "--config", "/path/to/config.json"]
    }
  }
}
Kiro MCP Configuration

Create or edit .kiro/settings/mcp.json:

{
  "mcpServers": {
    "redmine": {
      "command": "uvx",
      "args": ["redmine-mcp-server"],
      "env": {
        "REDMINE_URL": "https://your-redmine-server.com",
        "REDMINE_API_KEY": "your_api_key_here",
        "LOG_LEVEL": "INFO"
      },
      "disabled": false,
      "autoApprove": ["list_projects", "get_project", "list_users"]
    }
  }
}

Available MCP Tools

The server provides the following MCP tools:

Ticket Operations

  • create_issue: Create a new Redmine ticket

    • Parameters: project_id, subject, description, tracker_id, assigned_to_id, etc.

  • update_issue: Update an existing ticket

    • Parameters: issue_id, plus any fields to update

  • get_issue: Retrieve ticket details

    • Parameters: issue_id

  • search_issues: Search for tickets

    • Parameters: project_id, status_id, assigned_to_id, subject, etc.

Project Operations

  • list_projects: Get list of accessible projects

  • get_project: Get detailed project information

    • Parameters: project_id

  • list_users: Get list of Redmine users

Development

Setting up Development Environment

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

# Install development dependencies
uv sync --dev

# Install pre-commit hooks (optional)
uv run pre-commit install

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=redmine_mcp_server --cov-report=html

# Run specific test categories
uv run pytest -m unit
uv run pytest -m integration

Code Quality

# Format code
uv run ruff format

# Check and fix linting issues
uv run ruff check --fix

# Type checking
uv run mypy src/

# Run all quality checks
uv run ruff check && uv run mypy src/ && uv run pytest

Project Structure

redmine-mcp-server/
ā”œā”€ā”€ src/
ā”‚   ā””ā”€ā”€ redmine_mcp_server/
ā”‚       ā”œā”€ā”€ __init__.py          # Package initialization
ā”‚       ā”œā”€ā”€ main.py              # Main entry point and CLI
ā”‚       ā”œā”€ā”€ mcp_server.py        # MCP protocol implementation
ā”‚       ā”œā”€ā”€ redmine_client.py    # Redmine API client
ā”‚       ā”œā”€ā”€ config.py            # Configuration management
ā”‚       ā”œā”€ā”€ models.py            # Data models
ā”‚       ā”œā”€ā”€ exceptions.py        # Custom exceptions
ā”‚       ā”œā”€ā”€ security.py          # Security utilities
ā”‚       ā”œā”€ā”€ logging_utils.py     # Logging configuration
ā”‚       ā”œā”€ā”€ decorators.py        # MCP tool decorators
ā”‚       ā”œā”€ā”€ issue_tools.py       # Ticket operation tools
ā”‚       ā””ā”€ā”€ project_tools.py     # Project operation tools
ā”œā”€ā”€ tests/                       # Test suite
ā”œā”€ā”€ docs/                        # Documentation
ā”œā”€ā”€ .env.example                 # Environment variables example
ā”œā”€ā”€ config.example.json          # Configuration file example
ā”œā”€ā”€ pyproject.toml               # Project configuration
ā””ā”€ā”€ README.md                    # This file

Troubleshooting

Common Issues

  1. Authentication Error: Verify your API key and Redmine URL
  2. Connection Timeout: Check network connectivity and increase timeout
  3. Permission Denied: Ensure your API key has necessary permissions
  4. SSL Certificate Error: Verify HTTPS configuration

Debug Mode

Enable debug logging for detailed information:

uvx redmine-mcp-server --debug

Or set environment variable:

export LOG_LEVEL=DEBUG

Logs

The server logs to stdout by default. In debug mode, you'll see:

  • HTTP requests and responses
  • MCP protocol messages
  • Detailed error information

Security Considerations

  • Store API keys securely using environment variables
  • Use HTTPS for Redmine connections
  • Set appropriate file permissions (600) for configuration files
  • Regularly rotate API keys
  • Monitor server logs for suspicious activity

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Run the test suite and quality checks
  6. Submit a pull request

License

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

Support

Changelog

See for version history and changes.