What is Redmine Mcp Server

Redmine MCP Server is a Model Context Protocol (MCP) server that integrates with Redmine project management systems, allowing AI assistants to interact with Redmine data seamlessly.

Use cases

Use cases include automating project updates, enabling AI-driven insights on project issues, integrating with other tools for enhanced project management, and providing real-time notifications for project activities.

How to use

To use Redmine MCP Server, set up the server environment, configure authentication methods, and utilize the provided RESTful API to access project management and issue tracking functionalities.

Key features

Key features include project management capabilities, issue tracking, support for multiple authentication methods, FastAPI integration for real-time communication, full MCP compatibility, and Docker support for easy deployment.

Where to use

Redmine MCP Server is suitable for software development teams, project management offices, and organizations that utilize Redmine for project tracking and require AI integration.

Redmine MCP Server

A Model Context Protocol (MCP) server that integrates with Redmine project management systems. This server provides seamless access to Redmine data through MCP tools, enabling AI assistants to interact with your Redmine instance.

Features

• Redmine Integration: List projects, view/create/update issues
• MCP Compliant: Full Model Context Protocol support with FastAPI and Server-Sent Events
• Flexible Authentication: Username/password or API key
• Docker Ready: Complete containerization support
• Comprehensive Testing: Unit, integration, and connection tests

Quick Start

# Clone and setup
git clone https://github.com/jztan/redmine-mcp-server
cd redmine-mcp-server

# Install dependencies
uv venv
source .venv/bin/activate
uv pip install -e .

# Configure environment
cp .env.example .env
# Edit .env with your Redmine settings

# Run the server
uv run fastapi dev src/redmine_mcp_server/main.py

The server runs on http://localhost:8000 with the MCP endpoint at /sse.
For container orchestration, a lightweight health check is available at /health.

Installation

Prerequisites

• Python 3.13+
• uv package manager
• Access to a Redmine instance

Configuration

Create and edit your environment configuration:

cp .env.example .env

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

# Authentication (choose one)
REDMINE_USERNAME=your_username
REDMINE_PASSWORD=your_password
# OR
# REDMINE_API_KEY=your_api_key

# Optional: Server settings
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

Note: API key authentication is preferred for security.

Usage

Running the Server

# Development mode (auto-reload)
uv run fastapi dev src/redmine_mcp_server/main.py

# Production mode
uv run python src/redmine_mcp_server/main.py

MCP Client Configuration

Configure your MCP client (e.g., VS Code settings.json):

{
  "mcp": {
    "servers": {
      "redmine": {
        "url": "http://127.0.0.1:8000/sse"
      }
    }
  }
}

Testing Your Setup

# Test Redmine connection
python tests/test_connection.py

# Run full test suite
python tests/run_tests.py --all

Available MCP Tools

get_redmine_issue(issue_id: int, include_journals: bool = True, include_attachments: bool = True)

Retrieves detailed information about a specific Redmine issue. When
include_journals is True (default) the returned dictionary also contains a
"journals" key with the issue’s comments. Set include_journals=False to skip
fetching comments for a lighter request. With include_attachments=True (the
default) the result includes an "attachments" list describing attached files.
Set include_attachments=False to omit this metadata.

list_redmine_projects()

Lists all accessible projects in the Redmine instance.

list_my_redmine_issues(**filters)

Lists issues assigned to the authenticated user. Uses the Redmine filter assigned_to_id="me". Additional query parameters can be supplied as keyword arguments.

create_redmine_issue(project_id: int, subject: str, description: str = "", **fields)

Creates a new issue in the specified project. Additional Redmine fields such as priority_id can be passed as keyword arguments.

update_redmine_issue(issue_id: int, fields: Dict[str, Any])

Updates an existing issue with the provided fields.

You may supply either status_id or status_name to change the issue
status. When status_name is given the tool resolves the corresponding
identifier automatically.

download_redmine_attachment(attachment_id: int, save_dir: str = '.')

Downloads a file attached to a Redmine issue. Returns the local path of the
saved file.

Docker Deployment

Quick Start with Docker

# Configure environment
cp .env.example .env.docker
# Edit .env.docker with your Redmine settings

# Run with docker-compose
docker-compose up --build

# Or run directly
docker build -t redmine-mcp-server .
docker run -p 8000:8000 --env-file .env.docker redmine-mcp-server

Production Deployment

Use the automated deployment script:

chmod +x deploy.sh
./deploy.sh

Development

Architecture

The server is built using:

• FastAPI: Modern web framework with automatic OpenAPI documentation
• FastMCP: Model Context Protocol implementation
• python-redmine: Official Redmine Python library
• Server-Sent Events (SSE): Real-time communication transport

Project Structure

redmine-mcp-server/
├── src/redmine_mcp_server/
│   ├── main.py              # FastAPI application entry point
│   └── redmine_handler.py   # MCP tools and Redmine integration
├── tests/                   # Comprehensive test suite
├── .env.example            # Environment configuration template
├── Dockerfile              # Container configuration
├── docker-compose.yml      # Multi-container setup
├── deploy.sh              # Deployment automation
└── pyproject.toml         # Project configuration

Adding New Tools

Add your tool function to src/redmine_mcp_server/redmine_handler.py:

@mcp.tool()
async def your_new_tool(param: str) -> Dict[str, Any]:
    """Tool description"""
    # Implementation here
    return {"result": "data"}

The tool will automatically be available through the MCP interface.

Testing

The project includes unit tests, integration tests, and connection validation.

Run tests:

# All tests
python tests/run_tests.py --all

# Unit tests only (default)
python tests/run_tests.py

# Integration tests (requires Redmine connection)
python tests/run_tests.py --integration

# With coverage report
python tests/run_tests.py --coverage

Test Requirements:

• Unit tests: No external dependencies (use mocks)
• Integration tests: Require valid Redmine server connection

Troubleshooting

Common Issues

1. Connection refused: Verify your REDMINE_URL and network connectivity
2. Authentication failed: Check your credentials in .env
3. Import errors: Ensure dependencies are installed: uv pip install -e .
4. Port conflicts: Modify SERVER_PORT in .env if port 8000 is in use

Debug Mode

Enable debug logging by modifying the FastAPI app initialization in main.py.

Contributing

Contributions are welcome! Please:

1. Open an issue for discussion
2. Run the full test suite: python tests/run_tests.py --all
3. Submit a pull request

License

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

Additional Resources

• CHANGELOG - Detailed version history
• Roadmap - Future development plans