MCP Redmine Server
YuSahrov/mcp-redmine-server
Integração completa do Redmine para gerenciamento de projetos via Claude
Ver no GitHubServidor MCP que integra Redmine com Claude Code, fornecendo acesso completo à API de gerenciamento de issues, workflows, wiki e Git. Permite criar, atualizar e consultar issues, gerenciar anexos, automatizar workflows com integração Git e administrar páginas wiki.
Instalação
npx convez-ai YuSahrov/mcp-redmine-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar criação e atualização de issues no Redmine via IA
- Gerenciar fluxos de trabalho com integração Git automática
- Consultar e filtrar issues por status, projeto e outros critérios
- Administrar documentação e wiki do projeto
Veredito

Solução robusta para equipes que usam Redmine e querem automatizar gerenciamento de issues via Claude. Oferece cobertura ampla da API com workflows Git nativos, ideal para DevOps e desenvolvimento colaborativo, mas requer configuração e conhecimento prévio de Redmine.
README
A tradução para o português deste README ainda está na fila.
MCP 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
-
redmine_get_issue - Get detailed issue information
- Includes description, status, priority, comments
- Returns full issue object with all metadata
-
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
-
redmine_add_comment - Add comment to issue
- Can optionally update issue status
- Useful for progress updates and status changes
File & Attachment Operations
-
redmine_upload_file - Upload file to Redmine
- Returns upload token for later use
- Supports all file types (images, documents, archives, etc.)
-
redmine_add_attachments - Attach files to existing issue
- Upload and attach multiple files in one operation
- Automatically adds comment with file list
Querying & Filtering
-
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
-
redmine_get_statuses - Get all available statuses
- Returns complete list of project statuses
- Useful for discovering valid status names
-
redmine_get_projects - Get all accessible projects
- Lists all Redmine projects available to your API key
- Useful for multi-project environments
-
redmine_get_project - Get project details
- Returns project info with trackers and enabled modules
-
redmine_get_project_issues - Get issues from specific project
- Supports pagination and filtering
- Filter by status, tracker, assignee
Relations & Hierarchy
-
redmine_get_issue_tree - Get full issue tree
- Returns main issue, related issues, and child issues
- Shows complete issue hierarchy
-
redmine_create_relation - Link two issues
- Relation types: relates, blocks, blocked, duplicates, precedes, follows
- Creates bidirectional relationships
Workflow Automation
-
redmine_start_fix - Start fix workflow
- Creates Git branch automatically
- Updates issue status to "In Progress"
- Adds workflow comment
-
redmine_complete_fix - Complete fix workflow
- Updates issue status to "Resolved"
- Adds completion comment with commit details
- Validates working directory is clean
Wiki Operations
-
redmine_wiki_get_page - Get wiki page content
- Returns page text and metadata
- Includes attachments information
-
redmine_wiki_get_index - List all wiki pages
- Returns index of all pages in project
-
redmine_wiki_put_page - Create or update wiki page
- Uses Redmine Textile markup
- Supports page hierarchy via parent_title
-
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
- Log in to your Redmine instance
- Go to "My account" (top right menu)
- Click "Show" under "API access key" on the right sidebar
- 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:
- Use
redmine_upload_fileto upload the screenshot - Use
redmine_create_issuewith 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:
-
Upload File: First, upload the file to get a token
// Returns: { token: "abc123...", filename: "screenshot.png", filesize: 12345 } -
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 callredmine_create_issuewithfile_paths: Create issue with attachments in one callredmine_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.pngorC:\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
- Check your
REDMINE_BASE_URLis correct - Verify your API key is valid
- Ensure you have network access to the Redmine server
- Check firewall/proxy settings
Git integration not working
- Ensure Git is installed and available in PATH
- Verify you're running commands from a Git repository
- 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
.envfiles or secure environment configuration - .gitignore: The
.envfile 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:
- Add tool definition to
ListToolsRequestSchemahandler - Implement tool logic in
CallToolRequestSchemahandler - Add corresponding helper function if needed
- 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.