redmine-mcp

Servidor MCP (Model Context Protocol) para interactuar con Redmine desde cualquier agente compatible: leer y buscar issues, ver detalle con notas, listar proyectos y catálogos, agregar notas, crear issues, cambiar estado, asignar y actualizar campos.

Publicado en npm como @speraltafibrazo/redmine-mcp — se consume con npx, sin clonar ni compilar nada.

Compatible con Claude Code, Claude Desktop, Cursor, OpenCode, Zed y cualquier cliente que soporte el protocolo MCP por stdio.

Requisitos previos

• Node.js 18+ — verificar con node --version (incluye npx)
• API key de Redmine — en tu instancia: Mi cuenta → Clave de acceso API
• URL de tu Redmine — ej. https://redmine.tu-empresa.com

No hace falta clonar el repo ni instalar el paquete manualmente: npx -y @speraltafibrazo/redmine-mcp lo descarga y ejecuta automáticamente la primera vez.

Cómo funciona la configuración

Todos los clientes siguen el mismo patrón: lanzan el servidor por stdio y le pasan dos variables de entorno.

| Campo | Valor | |---|---| | command | npx | | args | ["-y", "@speraltafibrazo/redmine-mcp"] | | env.REDMINE_URL | https://redmine.tu-empresa.com | | env.REDMINE_API_KEY | tu API key personal de Redmine |

Cada persona usa su propia API key. Nunca la commitees a un repo: ponela en la config de usuario del cliente (no en archivos versionados).

A continuación, el bloque exacto para cada cliente.

Claude Code (CLI)

Opción A — comando (recomendado). Registra el server a nivel de usuario (queda activo en todos tus proyectos):

claude mcp add redmine -s user \
  --env REDMINE_URL=https://redmine.tu-empresa.com \
  --env REDMINE_API_KEY=<tu_key> \
  -- npx -y @speraltafibrazo/redmine-mcp

En Windows (PowerShell), en una sola línea:

claude mcp add redmine -s user --env REDMINE_URL=https://redmine.tu-empresa.com --env REDMINE_API_KEY=<tu_key> -- npx -y @speraltafibrazo/redmine-mcp

Opción B — editar la config manualmente. En ~/.claude.json, dentro de "mcpServers":

"redmine": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@speraltafibrazo/redmine-mcp"],
  "env": {
    "REDMINE_URL": "https://redmine.tu-empresa.com",
    "REDMINE_API_KEY": "tu_api_key_personal"
  }
}

Para compartir la config con el equipo por git, poné el mismo bloque en un .mcp.json en la raíz del proyecto — pero en ese caso dejá las credenciales fuera (que cada dev las tenga en su ~/.claude.json).

Claude Desktop

Editá el archivo de configuración:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Agregá el bloque dentro de "mcpServers":

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@speraltafibrazo/redmine-mcp"],
      "env": {
        "REDMINE_URL": "https://redmine.tu-empresa.com",
        "REDMINE_API_KEY": "tu_api_key_personal"
      }
    }
  }
}

Reiniciá Claude Desktop para que tome los cambios.

Cursor

Editá (o creá) ~/.cursor/mcp.json para configuración global, o .cursor/mcp.json en la raíz del proyecto para que aplique solo a ese repo:

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@speraltafibrazo/redmine-mcp"],
      "env": {
        "REDMINE_URL": "https://redmine.tu-empresa.com",
        "REDMINE_API_KEY": "tu_api_key_personal"
      }
    }
  }
}

También podés hacerlo por UI desde Cursor → Settings → MCP → Add new server.

OpenCode

Editá opencode.json (en la raíz del proyecto) o ~/.config/opencode/opencode.json (global) y agregá dentro de "mcp":

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "redmine": {
      "type": "local",
      "command": ["npx", "-y", "@speraltafibrazo/redmine-mcp"],
      "enabled": true,
      "environment": {
        "REDMINE_URL": "https://redmine.tu-empresa.com",
        "REDMINE_API_KEY": "tu_api_key_personal"
      }
    }
  }
}

OpenCode usa command como array (no string) y la clave de variables es environment (no env).

Zed

Editá settings.json:

• macOS / Linux: ~/.config/zed/settings.json
• Windows: %APPDATA%\Zed\settings.json
• O desde el editor: paleta de comandos → agent: add context server

Agregá dentro de "context_servers":

{
  "context_servers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@speraltafibrazo/redmine-mcp"],
      "env": {
        "REDMINE_URL": "https://redmine.tu-empresa.com",
        "REDMINE_API_KEY": "tu_api_key_personal"
      }
    }
  }
}

Zed usa la clave context_servers (no mcpServers). Reinicia el server solo automáticamente al guardar. Si tu versión de Zed no lo levanta, agregá "source": "custom" dentro del bloque "redmine".

Cualquier otro cliente MCP (stdio)

Windsurf, Continue, Cline, Zed extensions, etc. El patrón genérico es siempre el mismo:

| Campo | Valor | |---|---| | command | npx | | args | ["-y", "@speraltafibrazo/redmine-mcp"] | | variables de entorno | REDMINE_URL y REDMINE_API_KEY |

Adaptá esos valores al schema JSON que use tu cliente (mcpServers, mcp, context_servers, etc.).

Verificar que funciona

Una vez configurado, pedile al agente:

list_projects

Si devuelve la lista de proyectos de Redmine, el servidor está conectado.

También podés probarlo con el inspector MCP oficial, pasando las variables inline:

REDMINE_URL=https://redmine.tu-empresa.com REDMINE_API_KEY=<tu_key> \
  npx @modelcontextprotocol/inspector npx -y @speraltafibrazo/redmine-mcp

En Windows (PowerShell):

$env:REDMINE_URL="https://redmine.tu-empresa.com"; $env:REDMINE_API_KEY="<tu_key>"; npx @modelcontextprotocol/inspector npx -y @speraltafibrazo/redmine-mcp

Tools disponibles

| Tool | Qué hace | |---|---| | list_issues | Lista/busca issues con filtros: proyecto, estado, asignado, tracker, versión/sprint, texto libre | | get_issue | Detalle completo de un issue: descripción, versión, jerarquía padre/hijo e historial de notas (con journal id para idempotencia) | | list_projects | Lista todos los proyectos accesibles con tu API key | | list_metadata | Catálogos para resolver IDs: statuses, trackers, priorities, users, versions (sprints; requiere project_id) | | add_note | Agrega una nota/comentario a un issue existente, y devuelve el id de la nota creada como [j#<id>] (Redmine responde sin cuerpo: lo resuelve una lectura interna, para no traer el historial al contexto) | | edit_journal | Corrige el texto de una nota ya publicada — sólo si sos el autor original (guarda de autoría, ver ADR-001); no permite borrado | | change_issue_status | Cambia el estado de un issue (ej. En progreso → Resuelto); si la llamada lleva nota, devuelve también su [j#<id>] | | create_issue | Crea un issue nuevo con todos sus campos (incluye issue padre y versión/sprint) | | assign_issue | Asigna o reasigna un issue a un usuario; si la llamada lleva nota, devuelve también su [j#<id>] | | update_issue | Actualiza avance, tracker, prioridad, fechas, asunto, descripción, issue padre y versión/sprint | | add_watcher | Agrega un observador (watcher) a un issue | | remove_watcher | Quita un observador (watcher) de un issue | | update_version | Cambia el estado (open/locked/closed) de una versión/sprint — permite reabrir un sprint cerrado para asignarle un issue y volver a cerrarlo |

Actualizar

Como los clientes usan npx -y, tomás la última versión publicada automáticamente al reiniciar el cliente. Para forzar una versión concreta, fijala en args: ["-y", "@speraltafibrazo/[email protected]"].

Para publicar nuevas versiones del server, ver PUBLISHING.md.

Desarrollo

Solo si vas a modificar el código del server:

git clone https://github.com/Fibrazo-SAS/mcp_redmine.git
cd mcp_redmine
npm install
npm run dev        # compila en modo watch
npm run typecheck  # chequeo de tipos sin emitir
npm test           # tests unitarios (fetch mockeado, no pega a Redmine real)

Para apuntar tu cliente al build local mientras desarrollás, usá "command": "node" con la ruta a dist/index.js en vez de npx.

Troubleshooting

El cliente no levanta el servidor MCP

• Verificá que tenés Node 18+: node --version
• Probá la descarga a mano: npx -y @speraltafibrazo/redmine-mcp (debería quedar esperando input por stdio; cortá con Ctrl+C)

Error de autenticación / 401

• Verificá que REDMINE_API_KEY es tu key actual
• Se regenera desde Mi cuenta → Clave de acceso API → Regenerar

Error de conexión / ECONNREFUSED

• Verificá que REDMINE_URL no tiene barra final y que la instancia es accesible desde tu red

Faltan variables de entorno

• El server aborta si no encuentra REDMINE_URL y REDMINE_API_KEY; confirmá que están en el bloque env (o environment en OpenCode) de tu cliente