guiziweb / mcp-redmine
MCP (Model Context Protocol) server for Redmine integration with AI assistants like Claude Desktop
Installs: 4
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 0
Forks: 0
Type:project
pkg:composer/guiziweb/mcp-redmine
Requires
- php: >=8.2
- ext-ctype: *
- kbsali/redmine-api: ^2.8
- symfony/console: 7.3.*
- symfony/flex: ^2
- symfony/framework-bundle: 7.3.*
- symfony/mcp-bundle: @dev
- symfony/monolog-bundle: ^3.10
- symfony/runtime: 7.3.*
- symfony/validator: 7.3.*
- symfony/yaml: 7.3.*
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^10.5
Conflicts
This package is auto-updated.
Last update: 2025-10-17 09:25:35 UTC
README
A secure, multi-user MCP (Model Context Protocol) server that integrates Redmine with AI assistants like Claude Desktop and Claude Code. Features OAuth2 authentication, encrypted credentials, and natural language interaction with your Redmine instance.
Features
- OAuth2 Authentication: Secure Google Sign-In for team authentication
- Multi-user Support: Each user has their own Redmine credentials
- Encrypted Storage: Credentials encrypted with Sodium (AES-256 equivalent)
- Email Whitelist: Domain-based access control (configurable)
- HTTP Transport: REST API with JWT tokens
- Smart Time Tracking: Natural language time logging with automatic summaries
Quick Start
For Users (Claude Desktop / Claude Code)
1. Get the Server URL
Ask your administrator for:
- Server URL (e.g.,
https://mcp-redmine.onrender.com) - Confirm your email is whitelisted
2. Configure Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"redmine": {
"url": "https://mcp-redmine.onrender.com"
}
}
}
3. Configure Claude Code
Edit ~/.config/claude-code/.mcp.json:
{
"mcpServers": {
"redmine": {
"url": "https://mcp-redmine.onrender.com"
}
}
}
4. Restart and Authenticate
- Restart Claude Desktop/Code
- First use will redirect you to Google Sign-In
- After authentication, provide your Redmine URL and API key
- Done! You can now interact with Redmine
For Administrators (Deployment)
Deploy on Render.com (free tier) using the included render.yaml blueprint. See Google OAuth Configuration section below for setup instructions.
Available Tools
| Tool | Description | Example Prompts |
|---|---|---|
| List Projects | Show all accessible Redmine projects | "Show my projects", "List all projects" |
| List Issues | List issues from a specific project | "Show issues from Mobile App project", "List tickets in #123" |
| Get Issue Details | Get comprehensive issue information | "Show details of issue #456", "Get issue #789 with journals" |
| List Time Entries | Retrieve time entries with smart filtering | "Show my hours this week", "Time entries from August", "My daily average" |
| Log Time | Log time to an issue interactively | "Log 2 hours to issue #123", "Add time to ticket #456" |
| List Activities | Show available time entry activities | "Show activity types", "What activities can I log?" |
Smart Features
- Date Intelligence: "last week", "this month", "August 2025"
- Automatic Summaries: Total hours, daily/weekly breakdowns
- Work Analysis: Hours per day, project breakdowns, patterns
- Interactive: Will ask for missing parameters
Architecture
graph TB
Client[Claude Client<br/>Desktop/Code]
subgraph Server["MCP Redmine Server"]
OAuth[OAuth2 Controller<br/>Google Sign-In + Email Whitelist]
DB[(DoctrineUserCredentialRepository<br/>Database + Sodium encryption<br/>SQLite dev / PostgreSQL prod)]
Factory[UserRedmineProviderFactory<br/>Per-user Redmine clients]
end
Redmine[Redmine API<br/>Your Instance]
Client -->|HTTP + JWT| OAuth
OAuth --> DB
DB --> Factory
Factory --> Redmine
style Client fill:#e1f5ff
style Server fill:#f5f5f5
style Redmine fill:#ffe1e1
Loading
Key Components:
- OAuth2 Controller: Handles Google authentication and email whitelist verification
- Credential Repository: Stores encrypted Redmine credentials (URL + API key) per user
- Provider Factory: Creates per-user Redmine API clients on-demand
- Encryption: Credentials encrypted at rest with Sodium (XSalsa20-Poly1305)
Development
Requirements
- PHP 8.2+
- Composer
- Sodium extension
- Access to Redmine instance with API enabled
Local Setup
# Clone repository git clone https://github.com/guiziweb/mcp-redmine.git cd mcp-redmine # Install dependencies composer install # Configure environment cp .env.example .env.local # Edit .env.local with your settings # Generate encryption key php -r "echo base64_encode(random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES)) . PHP_EOL;" # Start development server (with ngrok for OAuth callback) ngrok http 8000 php -S localhost:8000 -t public/
Environment Variables
Required:
APP_URL: Your server URL (ngrok for dev, custom domain for prod)GOOGLE_CLIENT_ID: From Google Cloud ConsoleGOOGLE_CLIENT_SECRET: From Google Cloud ConsoleENCRYPTION_KEY: Base64-encoded 32-byte Sodium keyJWT_SECRET: Random string for JWT signing
Optional:
APP_ENV:devorprod(default:dev)
Testing
# Run all tests composer test # Run specific test vendor/bin/phpunit tests/Tools/ListProjectsToolTest.php # Static analysis vendor/bin/phpstan analyze # Code style vendor/bin/php-cs-fixer fix
Google OAuth Configuration
1. Create Google Cloud Project
- Go to Google Cloud Console
- Create new project: "MCP Redmine"
- Enable Google+ API
2. Configure OAuth Consent Screen
- APIs & Services → OAuth consent screen
- User Type: External
- App name: "MCP Redmine"
- Scopes:
email,profile(non-sensitive, no validation required) - Test users: Add your team emails (or skip if using domain whitelist)
3. Create OAuth2 Credentials
- APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID
- Application type: Web application
- Authorized redirect URIs:
- Development:
https://your-ngrok-url.ngrok-free.dev/oauth/google-callback - Production:
https://mcp-redmine.onrender.com/oauth/google-callback
- Development:
- Save and copy Client ID and Client Secret
4. Email Whitelist
Configure allowed users via environment variables in .env.local or Render dashboard:
# Allow entire domains (comma-separated) ALLOWED_EMAIL_DOMAINS=example.com # Allow specific emails (comma-separated) ALLOWED_EMAILS=alice@example.com,bob@example.com
Both options can be combined. If neither is set, no users will be able to access the application.
Troubleshooting
"Email not authorized"
Your email is not in the whitelist. Contact your administrator.
"No credentials found for user"
First-time users need to authenticate via OAuth and provide Redmine credentials.
OAuth redirect fails
- Verify
APP_URLmatches your actual server URL - Check Google Console redirect URIs match exactly
- Ensure OAuth2 credentials are correct in environment
"Service unavailable" in production
- Check server logs
- Verify all environment variables are set
- Ensure encryption key is properly configured
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Run tests and code quality checks
- Submit a pull request
License
MIT
Support
- Issues: GitHub Issues