mcp-redmine

Un servidor de Model Context Protocol que conecta Claude (Desktop o Code) — o cualquier otro cliente MCP — a una instancia de Redmine a través de su API REST.

Expone 73 herramientas que cubren, en la práctica, toda la API REST estable de Redmine: incidencias, relaciones, proyectos, membresías, versiones, categorías, usuarios, grupos, roles, wiki, seguimiento de tiempo, adjuntos, archivos de proyecto, noticias y búsqueda. Apunta tu agente a un proyecto de Redmine y deja que lea y gestione incidencias, registre tiempo, edite páginas wiki y administre usuarios, todo mediante conversación natural.

Características

• Cobertura completa de lectura/escritura de incidencias, incluyendo actualizaciones masivas, relaciones, observadores y comentarios.

• Administración de proyectos: crear/actualizar/archivar proyectos, gestionar miembros, versiones y categorías.

• Administración de usuarios y grupos, sin herramientas de "eliminar usuario" o "eliminar proyecto" a propósito — ver Seguridad.

• Wiki, incluyendo páginas anidadas y archivos adjuntos.

• Seguimiento de tiempo, adjuntos, archivos de proyecto, noticias y búsqueda de texto completo.

• Errores legibles: cada fallo devuelve una frase clara extraída de la propia respuesta de validación de Redmine, no un rastro de pila crudo.

• Nada que ejecutar: un único proceso de Python que habla stdio con tu cliente MCP — sin base de datos, sin servidor que alojar, sin Docker requerido.

Related MCP server: redmine-mcp

Requisitos previos

• Python 3.10+

• Una instancia de Redmine con la API REST habilitada:

  1. En Redmine, ve a Administración → Configuración → API y habilita "Habilitar servicio web REST" (si no está ya activado).

  2. Ve a Mi cuenta → Clave de acceso a la API y copia el valor.

Instalación

La distribución se publica como mcp-redmine-rest, y el comando que instala es mcp-redmine-rest. El nombre más corto mcp-redmine en PyPI pertenece a un proyecto no relacionado — no instales ese esperando este servidor.

Si estás apuntando un agente de IA a este repositorio para que haga la configuración por ti, llms-install.md está escrito exactamente para eso.

Con uv (recomendado)

uv tool install mcp-redmine-rest

Con pip

pip install mcp-redmine-rest

Desde el código fuente

git clone https://github.com/alsimoes/mcp-redmine-rest.git
cd mcp-redmine-rest

python3 -m venv venv && source venv/bin/activate    # Linux/Mac

pip install -e .

En Windows, usa py y PowerShell en lugar de un shell de Git Bash/WSL — crear o recrear el venv desde un shell de estilo Unix en Windows sobrescribe venv\pyvenv.cfg con una ruta home de Unix, y cada lanzamiento posterior de venv\Scripts\python.exe falla con No Python at '/usr/bin\python.exe' (o similar):

git clone https://github.com/alsimoes/mcp-redmine-rest.git
cd mcp-redmine-rest

py -3 -m venv venv
.\venv\Scripts\Activate.ps1

pip install -e .

Configuración

El servidor lee su configuración de variables de entorno:

Mantener la clave fuera de la configuración del cliente

Los valores que faltan en el entorno se leen de un archivo .env, por lo que la clave de API no tiene que estar en texto plano en la configuración de tu cliente MCP. Copia .env.example a .env en la raíz del repositorio y complétalo — cada variable de la tabla anterior se respeta, por lo que el bloque env del cliente se puede eliminar por completo:

REDMINE_URL=https://redmine.example.com
REDMINE_API_KEY=your_api_key_here
REDMINE_TIMEOUT=15

El archivo está en gitignore. Las variables ya presentes en el entorno siempre ganan, por lo que un bloque env en la configuración de tu cliente aún lo anula. Para mantener el archivo en otro lugar, establece REDMINE_ENV_FILE a su ruta completa.

Esto importa especialmente en Claude Desktop: lanza servidores MCP con un entorno mínimo que construye él mismo, por lo que las variables que exportas en tu shell o estableces con setx nunca llegan al servidor. Usa el bloque env o un archivo .env.

Claude Desktop

Edita (o crea) el archivo de configuración de Claude Desktop:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "redmine": {
      "command": "mcp-redmine-rest",
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Si instalaste desde el código fuente en lugar de mediante uv tool install / pip install, apunta command al intérprete de tu entorno virtual y pasa el script como argumento:

{
  "mcpServers": {
    "redmine": {
      "command": "/full/path/to/mcp-redmine/venv/bin/python",
      "args": ["-m", "mcp_redmine"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

En Windows, apunta command a venv\Scripts\python.exe (con \\ escapado en JSON):

{
  "mcpServers": {
    "redmine": {
      "command": "C:\\full\\path\\to\\mcp-redmine\\venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_redmine"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Reinicia Claude Desktop después. El icono de herramientas (🔨) debería mostrar las herramientas de Redmine como disponibles.

Claude Code

claude mcp add redmine \
  --env REDMINE_URL=https://redmine.example.com \
  --env REDMINE_API_KEY=your_api_key_here \
  -- mcp-redmine-rest

Confirma con:

claude mcp list

Cline (VS Code)

Abre la configuración de MCP desde la paleta — Ctrl+Shift+P → Cline: Open MCP Config File — o haz clic en el engranaje junto a "MCP Servers" en la barra lateral de Cline y elige Configure MCP Servers. Cualquiera de los dos abre cline_mcp_settings.json; añade el servidor allí:

{
  "mcpServers": {
    "redmine": {
      "command": "mcp-redmine-rest",
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Usa el comando de la paleta en lugar de editar el archivo a mano — vive en lo profundo del almacenamiento global de VS Code (.../User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json), y la ruta difiere según la plataforma.

Si mcp-redmine-rest no está en el PATH que ve VS Code, usa la forma de módulo en su lugar — "command" apuntando al intérprete que tiene el paquete instalado, con "args": ["-m", "mcp_redmine"], exactamente como los ejemplos de Claude Desktop anteriores.

Recarga la ventana (Ctrl+Shift+P → Developer: Reload Window) y el servidor debería aparecer como conectado bajo "MCP Servers". Un tutorial más largo, que cubre el .mcp.json del espacio de trabajo y la interfaz de Añadir Servidor, está en CLINE_SETUP.md.

Otros clientes MCP

Cualquier cliente que pueda lanzar un proceso local y hablar MCP sobre stdio funciona de la misma manera: ejecuta mcp-redmine-rest (o python -m mcp_redmine) con REDMINE_URL y REDMINE_API_KEY establecidas en su entorno.

Ejecutar localmente (opcional)

Útil para una comprobación rápida antes de conectar el servidor a un cliente:

cp .env.example .env   # then edit .env with your values
export $(grep -v '^#' .env | xargs)   # or use a tool like direnv
mcp-redmine-rest

Si no hay error de conexión, el servidor está listo — espera mensajes MCP en stdin/stdout, por lo que no ver nada en la terminal es normal. Pulsa Ctrl+C para detenerlo.

Ejemplos de uso

Una vez configurado, solo habla con el agente:

• "Lista las incidencias abiertas asignadas a mí en el proyecto Website."

• "Crea un error en Website titulado 'El botón de inicio de sesión no responde en móvil', prioridad alta."

• "Mueve las incidencias #101, #104 y #110 a En Progreso y asígnalas a Alice."

• "Registra 3.5 horas en la incidencia #204 para hoy, actividad Desarrollo."

• "¿Qué hay en la página wiki 'Deployment' para el proyecto Infra?"

• "Busca 'timeout' en todos los proyectos."

Herramientas disponibles

73 herramientas, agrupadas por recurso. La referencia completa — firmas, parámetros, forma de retorno y las advertencias que importan (como cómo precedes reprograma incidencias, o que list_custom_fields requiere un administrador) — está en docs/TOOLS.md.

Cobertura de la API

Las dos omisiones son deliberadas. delete_project y delete_user son irreversibles y eliminan contenido de otros usuarios junto con ellos: incidencias, entradas de tiempo, páginas wiki, autoría. archive_project y update_user con status=3 cubren el caso de uso real de forma reversible. La eliminación definitiva sigue siendo una operación de la interfaz web, donde la confirmación es explícita y humana. Consulta SECURITY.md para conocer el razonamiento completo.

Los seguimientos, estados de incidencias, prioridades y roles no tienen operaciones de escritura en la API de Redmine: solo se configuran en Administración. Eso no es una carencia en este servidor.

Fuera de la API REST estable y, por tanto, fuera del alcance de este servidor: repositorios y conjuntos de cambios, protección de páginas wiki y pantallas de configuración de la instancia.

Mensajes de error

Los errores se gestionan de forma centralizada: cuando Redmine rechaza una llamada, el servidor lee el cuerpo de la respuesta — ahí es donde está la explicación real, en el campo errors — y devuelve esa frase. Si no hay un cuerpo útil, recurre al código de estado HTTP con un motivo probable:

Esto se aplica a cada herramienta, tanto de lectura como de escritura.

Solución de problemas

• "REDMINE_URL and REDMINE_API_KEY must be set": el servidor comprueba su configuración al iniciar y sale inmediatamente con este mensaje en lugar de arrancar de forma incorrecta. Revisa el bloque env en la configuración de tu cliente MCP.

• Cada llamada falla con un error de red: confirma que el proceso del servidor puede alcanzar realmente REDMINE_URL — los clientes MCP ejecutan el servidor como un proceso local, por lo que necesita el mismo acceso de red que tu máquina, no el del navegador.

• Error 401 en cada llamada: la clave de API es incorrecta, o "Habilitar servicio web REST" está desactivado en la configuración de Redmine.

• Error 403 en una herramienta específica: normalmente es un permiso que falta en el rol del usuario propietario de la clave de API. get_role muestra exactamente qué permisos tiene un rol.

• Una herramienta responde 404 cuando esperarías que funcionara: algunos endpoints (update_journal_note, update_news/delete_news, update_attachment) se añadieron en versiones específicas de Redmine — consulta docs/TOOLS.md para conocer la versión mínima de cada uno.

Seguridad

Consulta SECURITY.md para conocer el modelo completo. En resumen: una clave de API otorga acceso equivalente al del usuario que la posee, así que crea un usuario de Redmine dedicado con un rol limitado a lo que quieres que el agente haga, y utiliza la clave de ese usuario — no intentes limitar al agente editando el código de este servidor.

La subida de archivos está deshabilitada hasta que establezcas REDMINE_UPLOAD_ROOTS. Las tres herramientas que suben un archivo local (attach_file_to_issue, attach_file_to_wiki_page, upload_project_file) rechazan cualquier ruta por defecto, precisamente porque un agente puede ser dirigido mediante contenido inyectado (un comentario de incidencia, una página wiki) a subir un archivo que nunca debía leer. Consulta SECURITY.md.

Contribuciones

Consulta CONTRIBUTING.md.

Licencia

MIT