# Redmine MCP Server
[](https://www.npmjs.com/package/@duongkhuong/mcp-redmine)
[](https://opensource.org/licenses/MIT)
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)
```bash
npm install -g @duongkhuong/mcp-redmine
```
### From Source
```bash
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`
```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`
```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`
```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](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) extension.
2. Open VS Code Settings (JSON).
3. Add the MCP configuration:
```json
{
"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)
```bash
npm start
```
### Testing with MCP Inspector
```bash
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:**
```json
{
"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
```bash
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
