Redmine Server

Model Context Protocol (MCP) server for Redmine integration. Provides comprehensive Redmine API access to Claude Code and other MCP-compatible AI assistants.

Features

• Issue Management: Create, read, update issues with full details
• File Attachments: Upload and attach files/images to issues
• Workflow Support: Start/complete fix workflows with Git integration
• Relations & Tree: Manage issue relations, subtasks, and hierarchies
• Status Filtering: Query issues by status with flexible filtering
• Comments: Add comments and update issue status
• Git Integration: Automatic branch creation and commit tracking
• Wiki Support: Full wiki page management (read, create, update, delete)

Available Tools

The server provides the following MCP tools:

Issue Operations

1. redmine_get_issue - Get detailed issue information

   • Includes description, status, priority, comments
   • Returns full issue object with all metadata

2. redmine_create_issue - Create new issue

   • Parameters: title, description, tracker_id, priority_id, parent_id, file_paths
   • Supports creating subtasks via parent_id
   • Can attach files during issue creation

3. redmine_add_comment - Add comment to issue

   • Can optionally update issue status
   • Useful for progress updates and status changes

File & Attachment Operations

4. redmine_upload_file - Upload file to Redmine

   • Returns upload token for later use
   • Supports all file types (images, documents, archives, etc.)

5. redmine_add_attachments - Attach files to existing issue

   • Upload and attach multiple files in one operation
   • Automatically adds comment with file list

Querying & Filtering

6. redmine_get_issues_by_status - Filter issues by status

   • Parameters: status_name, limit, project_id
   • Returns issues with specific status (e.g., "New", "In Progress")
   • Can filter by project or get from all projects

7. redmine_get_statuses - Get all available statuses

   • Returns complete list of project statuses
   • Useful for discovering valid status names

8. redmine_get_projects - Get all accessible projects

   • Lists all Redmine projects available to your API key
   • Useful for multi-project environments

9. redmine_get_project - Get project details

   • Returns project info with trackers and enabled modules

10. redmine_get_project_issues - Get issues from specific project

    • Supports pagination and filtering
    • Filter by status, tracker, assignee

Relations & Hierarchy

11. redmine_get_issue_tree - Get full issue tree

    • Returns main issue, related issues, and child issues
    • Shows complete issue hierarchy

12. redmine_create_relation - Link two issues

    • Relation types: relates, blocks, blocked, duplicates, precedes, follows
    • Creates bidirectional relationships

Workflow Automation

13. redmine_start_fix - Start fix workflow

    • Creates Git branch automatically
    • Updates issue status to "In Progress"
    • Adds workflow comment

14. redmine_complete_fix - Complete fix workflow

    • Updates issue status to "Resolved"
    • Adds completion comment with commit details
    • Validates working directory is clean

Wiki Operations

15. redmine_wiki_get_page - Get wiki page content

    • Returns page text and metadata
    • Includes attachments information

16. redmine_wiki_get_index - List all wiki pages

    • Returns index of all pages in project

17. redmine_wiki_put_page - Create or update wiki page

    • Uses Redmine Textile markup
    • Supports page hierarchy via parent_title

18. redmine_wiki_delete_page - Delete wiki page

    • Permanently removes wiki page from project

Installation

Global Installation (Recommended)

Install the MCP server globally for use across all projects:

# Install dependencies
npm install

# Create global link
npm link

# Verify installation
which mcp-redmine

Local Installation

Or install locally in a specific project:

npm install

Configuration

Environment Variables

Create a .env file or set environment variables:

# Required
export REDMINE_API_KEY=your_api_key_here

# Optional (defaults shown)
export REDMINE_BASE_URL=https://3cad.tech
export REDMINE_PROJECT_ID=8
export REDMINE_PROJECT_IDENTIFIER=cad-tech

Get Your Redmine API Key

1. Log in to your Redmine instance
2. Go to "My account" (top right menu)
3. Click "Show" under "API access key" on the right sidebar
4. Copy the API key

Claude Code Integration

Method 1: Global MCP Configuration

Add to your global Claude Code MCP settings (~/.config/claude-code/mcp.json or similar):

{
  "mcpServers": {
    "redmine": {
      "command": "mcp-redmine",
      "env": {
        "REDMINE_API_KEY": "your_api_key_here",
        "REDMINE_BASE_URL": "https://3cad.tech",
        "REDMINE_PROJECT_ID": "8",
        "REDMINE_PROJECT_IDENTIFIER": "cad-tech"
      }
    }
  }
}

Method 2: Project-Specific Configuration

Add to your project's .claude/mcp.json:

{
  "mcpServers": {
    "redmine": {
      "command": "node",
      "args": ["path/to/mcp-redmine-server/index.js"],
      "env": {
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Method 3: Use with dotenv

If using local installation with .env file:

{
  "mcpServers": {
    "redmine": {
      "command": "node",
      "args": ["-r", "dotenv/config", "path/to/mcp-redmine-server/index.js"],
      "cwd": "path/to/mcp-redmine-server"
    }
  }
}

Usage Examples

Once configured in Claude Code, the AI assistant can use these tools automatically:

Example Conversations

User: "Show me all issues that are in progress"

Claude will use redmine_get_issues_by_status with status_name: "In Progress"

---

User: "Create a new bug for the login page issue"

Claude will use redmine_create_issue with appropriate tracker_id

---

User: "Start working on issue #42"

Claude will use redmine_start_fix to:

• Create a Git branch fix/issue-42-...
• Update issue status to "In Progress"
• Add comment with branch name

---

User: "I've fixed issue #42, the login validation is working now"

Claude will use redmine_complete_fix to:

• Update status to "Resolved"
• Add completion comment with commits
• Provide next steps (PR, merge, etc.)

---

User: "Show me the full tree of issue #78"

Claude will use redmine_get_issue_tree to show:

• Main issue details
• All related issues
• All child/subtask issues

---

User: "Create a bug report for the login issue and attach the screenshot from my Desktop"

Claude will:

1. Use redmine_upload_file to upload the screenshot
2. Use redmine_create_issue with the upload token to create issue with attachment

---

User: "Add these error logs to issue #150: /path/to/error.log and /path/to/debug.log"

Claude will use redmine_add_attachments to:

• Upload both log files
• Attach them to issue #150
• Add comment with file list

---

User: "Create a new feature request with the mockup image attached"

Claude will use redmine_create_issue with file_paths parameter to create issue with attachment in one step

File Upload API Details

How File Attachments Work

Redmine API uses a two-step process for file attachments:

1. Upload File: First, upload the file to get a token

   // Returns: { token: "abc123...", filename: "screenshot.png", filesize: 12345 }
   

2. Attach to Issue: Use the token when creating/updating an issue

   // The token is automatically used in issue creation/update
   

The MCP server simplifies this by handling both steps automatically:

• redmine_add_attachments: Upload files and attach them in one call
• redmine_create_issue with file_paths: Create issue with attachments in one call
• redmine_upload_file: Manual upload if you need the token for later use

Supported File Types

All file types are supported:

• Images: PNG, JPG, GIF, SVG, etc.
• Documents: PDF, DOC, DOCX, TXT, MD, etc.
• Archives: ZIP, TAR, GZ, RAR, etc.
• Code: JS, PY, JAVA, etc.
• Logs: LOG, TXT, etc.
• Any other binary files

File Path Requirements

• Must be absolute paths (e.g., /home/user/screenshot.png or C:\Users\User\image.png)
• Files must exist and be readable
• No size limit enforced by MCP server (Redmine server may have limits)

Testing

Test the MCP server manually:

# Set environment variables
export REDMINE_API_KEY=your_api_key_here

# Run server (it communicates via stdio)
node index.js

# In another terminal, use MCP client to test
# Or test with Claude Code directly

Testing File Uploads

# Example: Create issue with attachment
# This is done automatically by Claude when using the MCP tools
# Just ask: "Create a bug report and attach /path/to/screenshot.png"

Troubleshooting

"REDMINE_API_KEY environment variable is required"

Make sure you've set the REDMINE_API_KEY environment variable or created a .env file.

"Connection failed" errors

1. Check your REDMINE_BASE_URL is correct
2. Verify your API key is valid
3. Ensure you have network access to the Redmine server
4. Check firewall/proxy settings

Git integration not working

1. Ensure Git is installed and available in PATH
2. Verify you're running commands from a Git repository
3. Check you have write permissions for the repository

Architecture

┌─────────────────────────────────────────┐
│         Claude Code / MCP Client        │
│                                         │
└──────────────┬──────────────────────────┘
               │ MCP Protocol (stdio)
               │
┌──────────────▼──────────────────────────┐
│        MCP Redmine Server               │
│                                         │
│  • Issue Management Tools               │
│  • File Upload & Attachments            │
│  • Workflow Automation                  │
│  • Git Integration                      │
│  • Wiki Management                      │
│  • Status & Filtering                   │
│                                         │
└──────────────┬──────────────────────────┘
               │ HTTPS API
               │
┌──────────────▼──────────────────────────┐
│         Redmine REST API                │
│                                         │
│  • Issues                               │
│  • Relations                            │
│  • Statuses                             │
│  • Projects                             │
│                                         │
└─────────────────────────────────────────┘

Security Notes

• API Key: Never commit your API key to version control
• Environment Variables: Use .env files or secure environment configuration
• .gitignore: The .env file is already in .gitignore
• Permissions: API key should have appropriate permissions in Redmine
• Git Operations: Server executes Git commands - ensure trusted environment

Development

Project Structure

mcp-redmine-server/
├── index.js              # Main MCP server implementation
├── package.json          # Node.js dependencies and metadata
├── .env.example          # Example environment configuration
├── .gitignore            # Git ignore rules
└── README.md             # This file

Adding New Tools

To add new Redmine functionality:

1. Add tool definition to ListToolsRequestSchema handler
2. Implement tool logic in CallToolRequestSchema handler
3. Add corresponding helper function if needed
4. Update this README with usage examples

Related Projects

• Model Context Protocol - MCP specification and SDKs
• Redmine API - Official Redmine REST API documentation

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Support

For issues specific to this MCP server, please open a GitHub issue.

For Redmine API questions, refer to the official documentation.