gmlee-ncurity/redmine-mcp-server

Redmine MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Redmine project management systems. This server provides comprehensive access to Redmine's features including issues, projects, time tracking, users, and wiki pages.

Features

Issue Management

• List, search, and filter issues
• Create, update, and delete issues
• View issue details with relationships and history

Project Management

• List all projects
• View project details and metadata
• Access project versions/milestones

Time Tracking

• Log time entries
• View and manage time records
• List time entry activities

User Management

• List users and groups
• Get user details and memberships
• Access current user information

Wiki Management

• List wiki pages with hierarchy
• Create, update, and delete wiki pages
• View wiki page history

Utilities

• List issue statuses, priorities, and trackers
• Custom API requests for advanced use cases
• Search issues, wiki pages, and more

Prerequisites

• Node.js >= 20.0.0
• A Redmine instance with API access enabled
• Redmine API key or username/password

Installation

Global Installation (recommended)

npm install -g @gmlee-ncurity/mcp-server-redmine

Direct Usage (no installation required)

npx @gmlee-ncurity/mcp-server-redmine

For local development

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

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Environment Variables

Configure the server using environment variables in your MCP client configuration:

# Required
REDMINE_URL=https://your-redmine-instance.com
REDMINE_API_KEY=your-api-key-here

# Optional: Basic auth (if API key not used)
# REDMINE_USERNAME=your-username
# REDMINE_PASSWORD=your-password

# Optional: SSL configuration
# REDMINE_SSL_VERIFY=true
# REDMINE_CA_CERT=/path/to/ca.crt

# Optional: Request configuration
# REDMINE_REQUEST_TIMEOUT=30000
# REDMINE_MAX_RETRIES=3

Getting a Redmine API Key

1. Log in to your Redmine instance
2. Go to "My account" (top right)
3. Click on "API access key" in the sidebar
4. Click "Show" to reveal your API key
5. Use the API key in your MCP configuration

Usage with Claude Desktop

Using the published package

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

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@gmlee-ncurity/mcp-server-redmine"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using local development version

{
  "mcpServers": {
    "redmine": {
      "command": "node",
      "args": ["/path/to/redmine-mcp-server/dist/index.js"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage with VS Code

You can use this MCP server with VS Code extensions that support the Model Context Protocol. Here's how to configure it:

Using Cline (Claude Dev) extension

1. Install the Cline extension from VS Code marketplace
2. Open VS Code settings (Cmd/Ctrl + ,)
3. Search for "Cline MCP"
4. Add the Redmine server configuration:

{
  "cline.mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@gmlee-ncurity/mcp-server-redmine"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using other MCP-compatible extensions

Check the extension's documentation for MCP server configuration. The pattern is typically similar to the above.

Available Tools

Issue Tools

• redmine_list_issues - List issues with filters
• redmine_get_issue - Get issue details
• redmine_create_issue - Create new issue
• redmine_update_issue - Update existing issue
• redmine_delete_issue - Delete issue

Project Tools

• redmine_list_projects - List all projects
• redmine_get_project - Get project details
• redmine_get_project_versions - Get project versions

User Tools

• redmine_list_users - List users
• redmine_get_current_user - Get current user info
• redmine_get_user - Get specific user details

Time Entry Tools

• redmine_list_time_entries - List time entries
• redmine_get_time_entry - Get time entry details
• redmine_create_time_entry - Create time entry
• redmine_update_time_entry - Update time entry
• redmine_delete_time_entry - Delete time entry
• redmine_list_time_entry_activities - List activities

Wiki Tools

• redmine_list_wiki_pages - List wiki pages
• redmine_get_wiki_page - Get wiki page content
• redmine_create_or_update_wiki_page - Create/update wiki page
• redmine_delete_wiki_page - Delete wiki page

Utility Tools

• redmine_list_statuses - List issue statuses
• redmine_list_priorities - List issue priorities
• redmine_list_trackers - List issue trackers
• redmine_custom_request - Make custom API request
• redmine_search - Search issues, wiki pages, and more

Example Queries

Once configured, you can ask your AI assistant questions like:

• "Show me all open issues assigned to me"
• "Create a new bug report for the API project"
• "Log 2 hours of work on issue #123 for today"
• "List all projects I have access to"
• "Show me the wiki page about deployment procedures"
• "What issues were updated this week?"
• "Update issue #456 to set priority to high"

Development

Running locally

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

Debugging with MCP Inspector

npm run inspector

This will start the MCP Inspector on http://localhost:5173

Security Considerations

• Always use HTTPS for your Redmine URL
• Store API keys securely and never commit them to version control
• Use environment variables for sensitive configuration
• Consider using read-only API keys when write access isn't needed
• Implement proper SSL certificate validation in production

Troubleshooting

Connection Issues

• Verify your Redmine URL is accessible
• Check that the API is enabled in Redmine settings
• Ensure your API key has the necessary permissions

Authentication Errors

• Confirm your API key is valid and active
• If using basic auth, verify username and password
• Check that your user account is active

SSL/TLS Issues

• For self-signed certificates, set REDMINE_SSL_VERIFY=false (not recommended for production)
• Provide the CA certificate path via REDMINE_CA_CERT

Desktop Extension (DXT) Support

This MCP server is also packaged as a Desktop Extension (DXT) for seamless integration with supported applications:

# Build DXT package
npm run build:bundle

The bundled version includes all dependencies and is optimized for distribution.

Development & Release

Automated Release Process

This project includes automated release scripts for easy version management and publishing:

# Release with patch version bump (1.0.1 -> 1.0.2)
npm run release

# Release with minor version bump (1.0.1 -> 1.1.0)
npm run release:minor

# Release with major version bump (1.0.1 -> 2.0.0)
npm run release:major

# Or use the script directly with options
./scripts/release.sh minor --skip-tests

The automated release process:

1. 🔄 Bumps the version in package.json
2. ✅ Runs all tests with proper environment setup
3. 🔍 Runs linting checks
4. 🔨 Builds the project
5. 📝 Commits changes with standardized message
6. 🚀 Pushes to repository
7. 📦 Publishes to npm registry
8. 🏷️ Creates GitHub release (if gh CLI is available)

CI/CD Pipeline

GitHub Actions automatically:

• Runs tests on Node.js 20.x and 22.x
• Checks linting and builds
• Auto-publishes to npm when version changes
• Creates GitHub releases
• Uploads test coverage reports

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

License

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