redmine-mcp

Servidor MCP local para consultar Redmine desde clientes compatibles con Model Context Protocol, como Codex, Claude Code o Claude Desktop.

El servidor se ejecuta por stdio, carga la configuracion desde variables de entorno o desde un fichero .env, y expone herramientas MCP para leer issues de Redmine.

Estado actual

Tools disponibles:

• get_issue: obtiene una issue de Redmine por ID.
• search_issues: lista issues de un proyecto.

El servidor muestra feedback de arranque por stderr para no interferir con el protocolo MCP por stdout. Ctrl+C detiene el servidor sin traceback.

Requisitos

• Python 3.12 o superior.
• uv para instalar y ejecutar el proyecto.
• Una instancia de Redmine con la API REST habilitada.
• Una API key de Redmine.

Configuracion

Crea un fichero .env local en la raiz del repositorio:

REDMINE_URL=https://redmine.example.org
REDMINE_API_KEY=tu_api_key

No subas .env al repositorio. Para documentar variables nuevas, usa .env.example con claves sin valores sensibles.

Tambien puedes definir esas variables directamente en el entorno del proceso:

$env:REDMINE_URL = "https://redmine.example.org"
$env:REDMINE_API_KEY = "tu_api_key"

Instalacion

Desde la raiz del proyecto:

uv sync

Esto crea o actualiza .venv e instala las dependencias declaradas en pyproject.toml.

Uso local

Arrancar el servidor MCP:

uv run redmine-mcp

O usando el ejecutable del entorno virtual:

.\.venv\Scripts\redmine-mcp.exe

Al iniciar deberias ver mensajes como estos en la terminal:

Iniciando servidor MCP de Redmine...
Redmine URL: https://redmine.example.org
API key de Redmine: configurada
Herramientas registradas: get_issue, search_issues
Transporte MCP: stdio
Servidor listo. Esperando mensajes MCP por stdin.

Para detenerlo manualmente, pulsa Ctrl+C.

Listar tools

Para ver las herramientas disponibles sin iniciar una sesion MCP:

uv run redmine-mcp --list-tools

Salida esperada:

Herramientas MCP disponibles:
- get_issue: Obtiene una issue de Redmine por ID.
- search_issues: Lista issues de un proyecto.

Para ver el esquema completo en JSON:

uv run redmine-mcp --list-tools --json

Un cliente MCP tambien puede consultar las tools mediante el metodo MCP tools/list despues de inicializar la sesion.

Uso desde Codex

Codex permite configurar servidores MCP en ~/.codex/config.toml. Ejemplo para este servidor local:

[mcp_servers.redmine]
command = "C:\\Users\\fvarrui\\GitHub\\redmine-mcp\\.venv\\Scripts\\redmine-mcp.exe"
cwd = "C:\\Users\\fvarrui\\GitHub\\redmine-mcp"
startup_timeout_sec = 10
tool_timeout_sec = 60

Si tienes .env en la raiz del proyecto y cwd apunta a esa raiz, no necesitas incluir secretos en el fichero de configuracion de Codex. Si prefieres pasar variables por configuracion, usa placeholders y evita compartir ese fichero:

[mcp_servers.redmine]
command = "C:\\Users\\fvarrui\\GitHub\\redmine-mcp\\.venv\\Scripts\\redmine-mcp.exe"
cwd = "C:\\Users\\fvarrui\\GitHub\\redmine-mcp"
env = { REDMINE_URL = "https://redmine.example.org", REDMINE_API_KEY = "tu_api_key" }

Verifica la configuracion:

codex mcp list

Uso desde Claude Code

Con Claude Code puedes registrar el servidor como MCP local por stdio. Ejecuta el comando desde una terminal donde claude este disponible:

claude mcp add --transport stdio --scope local redmine -- "C:\Users\fvarrui\GitHub\redmine-mcp\.venv\Scripts\redmine-mcp.exe"

Si no vas a depender de .env, pasa las variables al registrar el servidor:

claude mcp add --transport stdio --scope local --env REDMINE_URL=https://redmine.example.org --env REDMINE_API_KEY=tu_api_key redmine -- "C:\Users\fvarrui\GitHub\redmine-mcp\.venv\Scripts\redmine-mcp.exe"

Comandos utiles:

claude mcp list
claude mcp get redmine

Dentro de Claude Code, usa /mcp para revisar servidores conectados y estado de autenticacion cuando aplique.

Uso desde Claude Desktop

En Claude Desktop, abre la configuracion de desarrollador o MCP y edita el fichero de configuracion que indique la aplicacion. Anade una entrada equivalente a esta:

{
  "mcpServers": {
    "redmine": {
      "type": "stdio",
      "command": "C:\\Users\\fvarrui\\GitHub\\redmine-mcp\\.venv\\Scripts\\redmine-mcp.exe",
      "args": [],
      "env": {
        "REDMINE_URL": "https://redmine.example.org",
        "REDMINE_API_KEY": "tu_api_key"
      }
    }
  }
}

Despues reinicia Claude Desktop. Si ya existe mcpServers, anade solo la entrada redmine conservando JSON valido.

Desarrollo

Estructura principal:

src/redmine_mcp/
  __init__.py   # carga de configuracion y wrapper del entry point
  __main__.py   # CLI, arranque MCP, feedback y parada limpia
  tools.py      # tools de Redmine y registro en FastMCP

Comandos utiles:

uv sync
uv run redmine-mcp --list-tools
uv run redmine-mcp --list-tools --json
uv run python -m py_compile src\redmine_mcp\__init__.py src\redmine_mcp\__main__.py src\redmine_mcp\tools.py

Para anadir una nueva tool:

1. Implementa la funcion en src/redmine_mcp/tools.py.
2. Dale un docstring claro; MCP lo usa como descripcion.
3. Registrala en register_redmine_tools(mcp).
4. Comprueba que aparece con uv run redmine-mcp --list-tools --json.

Las llamadas HTTP a Redmine deben ir encapsuladas en helpers o adaptadores. Evita hacer llamadas externas en tests unitarios; usa mocks o fixtures.

Troubleshooting

KeyError: REDMINE_URL o KeyError: REDMINE_API_KEY:

Define las variables en .env o en el entorno del proceso.

401 o 403 desde Redmine:

Revisa la API key, permisos del usuario y que la API REST de Redmine este habilitada.

El cliente MCP no muestra tools:

Ejecuta uv run redmine-mcp --list-tools para comprobar el servidor fuera del cliente. Si funciona, revisa la ruta command, el cwd y las variables de entorno configuradas en Codex o Claude.

El servidor parece no imprimir nada por stdout:

Es esperado. En modo MCP por stdio, stdout se reserva para mensajes del protocolo. El feedback humano se escribe por stderr.

Referencias

• OpenAI Codex: configuracion de MCP en ~/.codex/config.toml: https://developers.openai.com/codex/config-reference
• OpenAI Docs MCP: ejemplo de alta y verificacion de servidores MCP en Codex: https://developers.openai.com/learn/docs-mcp
• Claude Code MCP: https://code.claude.com/docs/en/mcp
• Claude Desktop MCP: https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop