Mcp Readmine MCP Server

Redmine MCP Server

An MCP (Model Context Protocol) server that allows AI agents to interact with the Redmine API to manage tickets, projects, users, and time entries.

Features

• ✅ Dual Authentication Support: Basic Auth + API Key
• ✅ Comprehensive Toolset for Redmine interaction:
  • get_issues - List issues with filters
  • get_issue - Get issue details including journals and attachments
  • get_projects - List projects
  • get_project - Get project details
  • get_project_members - List project members (Users)
  • get_project_versions - List project versions (Milestones)
  • search_issues - Search issues by keyword
  • create_issue - Create a new issue
  • update_issue - Update an existing issue
  • add_comment - Add a comment to an issue
  • delete_issue - Delete an issue
  • log_time - Log time entries
  • get_time_entries - List logged time entries
  • get_time_entry_activities - List available time entry activities
• ✅ Type-safe with TypeScript and Zod validation
• ✅ Pagination support for all list endpoints

Installation

From npm (Recommended)

npm install -g @duongkhuong/mcp-redmine

From Source

git clone git@github.com:vfa-khuongdv/mcp_readmine.git
cd mcp_readmine
npm install
npm run build

Configuration

You need to provide the following environment variables:

• REDMINE_URL - URL of your Redmine instance (e.g., https://redmine.example.com)
• REDMINE_API_KEY - API key from your account settings
• REDMINE_USERNAME - Username for Basic Authentication
• REDMINE_PASSWORD - Password for Basic Authentication

Note: The Redmine API often requires BOTH Basic Auth (username/password) AND an API Key for full access depending on server configuration.

Usage

With Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@duongkhuong/mcp-redmine"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "your_api_key_here",
        "REDMINE_USERNAME": "your_username",
        "REDMINE_PASSWORD": "your_password"
      }
    }
  }
}

Restart Claude Desktop to load the MCP server.

With Cursor IDE

Add to your Cursor configuration file:

macOS/Linux: ~/.cursor/mcp.json

Windows: %APPDATA%\Cursor\User\mcp.json

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@duongkhuong/mcp-redmine"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "your_api_key_here",
        "REDMINE_USERNAME": "your_username",
        "REDMINE_PASSWORD": "your_password"
      }
    }
  }
}

Restart Cursor to load the MCP server.

With VS Code

Option 1: Using mcp.json (No extension required)

Create or edit your MCP configuration file:

macOS/Linux: ~/.vscode/mcp.json

Windows: %APPDATA%\Code\User\mcp.json

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@duongkhuong/mcp-redmine"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "your_api_key_here",
        "REDMINE_USERNAME": "your_username",
        "REDMINE_PASSWORD": "your_password"
      }
    }
  }
}

Reload VS Code to load the MCP server.

Option 2: Using Cline Extension

1. Install the Cline extension.
2. Open VS Code Settings (JSON).
3. Add the MCP configuration:

{
  "cline.mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@duongkhuong/mcp-redmine"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "your_api_key_here",
        "REDMINE_USERNAME": "your_username",
        "REDMINE_PASSWORD": "your_password"
      }
    }
  }
}

Reload VS Code to load the MCP server.

How to get your Redmine API Key

1. Log in to your Redmine instance.
2. Go to My account (top right corner).
3. Click on API access key (right sidebar or link).
4. Click Show to reveal the key.
5. Copy the API key and paste it into your configuration.

Running Standalone (Development)

npm start

Testing with MCP Inspector

npx @modelcontextprotocol/inspector npx -y @duongkhuong/mcp-redmine

Available Tools

1. get_issues

Get a list of issues/tickets with optional filters.

Parameters:

• project_id (number, optional) - Filter by project ID
• status_id (number | "open" | "closed" | "*", optional) - Filter by status
• assigned_to_id (number, optional) - Filter by assignee ID
• limit (number, optional) - Number of results (1-100, default: 25)
• offset (number, optional) - Pagination offset (default: 0)

Example:

{
  "project_id": 1,
  "status_id": "open",
  "limit": 10
}

2. get_issue

Get detailed information about a specific issue by ID, including journals, attachments, and relations.

Parameters:

• issue_id (number, required) - The ID of the issue

3. get_projects

Get a list of all projects.

Parameters:

• limit (number, optional) - Number of results (1-100, default: 25)
• offset (number, optional) - Pagination offset (default: 0)

4. get_project

Get detailed information about a specific project by ID.

Parameters:

• project_id (number, required) - The ID of the project

5. get_project_members

Get a list of project members (users) in a specific project.

Parameters:

• project_id (number, required) - The ID of the project
• limit (number, optional) - Number of results (1-100, default: 25)
• offset (number, optional) - Pagination offset (default: 0)

6. get_project_versions

Get a list of versions (milestones) for a specific project.

Parameters:

• project_id (number, required) - The ID of the project

7. search_issues

Search for issues by keyword in the subject field.

Parameters:

• query (string, required) - Search keyword
• limit (number, optional) - Number of results (1-100, default: 25)
• offset (number, optional) - Pagination offset (default: 0)

8. log_time

Log time stats for an issue or project.

Parameters:

• issue_id (number, optional) - The ID of the issue to log time for
• project_id (number, optional) - The ID of the project to log time for
• hours (number, required) - The number of hours to log
• activity_id (number, optional) - The ID of the activity
• comments (string, optional) - Short comment for the time entry
• spent_on (string, optional) - Date the time was spent (YYYY-MM-DD)

9. get_time_entries

Get a list of time entries with filters.

Parameters:

• project_id (number, optional) - Filter by project
• user_id (number, optional) - Filter by user
• from (string, optional) - Start date (YYYY-MM-DD)
• to (string, optional) - End date (YYYY-MM-DD)
• limit (number, optional) - Number of results (1-100, default: 25)
• offset (number, optional) - Pagination offset (default: 0)

10. get_time_entry_activities

Get a list of available time entry activities.

Parameters: None

11. create_issue

Create a new issue/ticket in Redmine.

Parameters:

• project_id (number, required) - ID of the project
• subject (string, required) - Title of the issue
• description (string, optional) - Detailed description
• tracker_id (number, optional) - Tracker ID (Bug, Feature, etc.)
• status_id (number, optional) - Status ID
• priority_id (number, optional) - Priority ID
• assigned_to_id (number, optional) - User ID to assign
• start_date (string, optional) - Start date (YYYY-MM-DD)
• due_date (string, optional) - Due date (YYYY-MM-DD)
• done_ratio (number, optional) - Completion percentage (0-100)
• fixed_version_id (number, optional) - Target version/milestone ID

12. update_issue

Update an existing issue/ticket. Only provided fields will be updated.

Parameters:

• issue_id (number, required) - ID of the issue to update
• project_id (number, optional) - Move to another project
• subject (string, optional) - Update title
• description (string, optional) - Update description
• tracker_id (number, optional) - Change tracker
• status_id (number, optional) - Change status
• priority_id (number, optional) - Change priority
• assigned_to_id (number, optional) - Reassign to another user
• start_date (string, optional) - Update start date
• due_date (string, optional) - Update due date
• done_ratio (number, optional) - Update completion percentage
• fixed_version_id (number, optional) - Update target version
• notes (string, optional) - Add a note/comment about the update

13. add_comment

Add a comment/note to an issue.

Parameters:

• issue_id (number, required) - ID of the issue
• notes (string, required) - Comment content

14. delete_issue

Delete an issue/ticket from Redmine.

Parameters:

• issue_id (number, required) - ID of the issue to delete

Example Prompts

Here are some example prompts you can use to interact with the Redmine MCP server:

🔍 Querying & Search

• "List all open bugs in project 'Mobile App'"
• "Show me high priority issues assigned to me"
• "Search for issues about 'login failure'"
• "Get details of issue #1234 including history"
• "Who are the members of project ID 5?"

📝 Issue Management

• "Create a new feature request in 'Web Platform' project: Add Dark Mode toggle"
• "Update issue #567 status to 'Resolved' and set done ratio to 100%"
• "Reassign issue #890 to user 'John Doe'"
• "Add a comment to issue #123: 'Fixed in commit abc1234'"
• "Delete issue #999"

⏱️ Time Tracking

• "Log 2 hours on issue #123 for 'Development'"
• "Show my time entries for this week"
• "List time entries for project 'Website Redesign' in January"
• "What are the available activities for time logging?"

Development

Watch mode

npm run dev

Project structure

mcp-redmine/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── redmine-client.ts # Redmine API client
│   ├── tools.ts          # MCP tool definitions
│   └── types.ts          # TypeScript types & Zod schemas
├── dist/                 # Compiled JavaScript
├── .env                  # Environment variables (gitignored)
├── .env.example          # Environment template
├── package.json
└── tsconfig.json

Troubleshooting

Authentication errors

Ensure you have provided:

• ✅ REDMINE_URL (no trailing slash)
• ✅ REDMINE_API_KEY (from account settings)
• ✅ REDMINE_USERNAME
• ✅ REDMINE_PASSWORD

Connection errors

• Check if REDMINE_URL is correct.
• Check network/firewall settings.
• Verify if API key is still valid.

Tool not found

• Ensure you have built the project: npm run build
• Restart your AI client (Claude, Cursor, VS Code) after updating config.

License

MIT