MCP AEMPS — CIMA

Qué hace

mcp-aemps envuelve la API REST CIMA de la AEMPS como un servidor MCP completo. Conecta Claude, GPT-4o, Gemini — o cualquier agente compatible con MCP — al registro oficial de medicamentos español. Consulta autorizaciones, fichas técnicas, notas de farmacovigilancia, problemas de suministro, equivalentes clínicos y más, en tiempo real.

Fuente de datos: CIMA (AEMPS) — API pública, sin PII, sin autenticación requerida. Postura de compliance: Proxy read-only. Audit trail por petición. Sin procesamiento de datos de pacientes.

Instalación

# pip
pip install mcp-aemps

# zero-install (recomendado para clientes CLI)
uvx mcp-aemps up
pipx run mcp-aemps up

# Docker (multi-arch: linux/amd64, linux/arm64) — mínimo 0.1.6
docker run -p 8765:8765 ghcr.io/romanpert/mcp-aemps:latest

# Docker Compose
docker compose up -d

Configuración del cliente en un solo comando

Tras pip install mcp-aemps, registra el servidor en tu cliente MCP con un único comando — sin editar JSON manualmente.

# Todos los clientes detectados a la vez
mcp-aemps install

# O elige uno
mcp-aemps install claude-desktop   # stdio por defecto (uvx auto-launch); HTTP via mcp-remote opcional
mcp-aemps install claude-code      # usa `claude mcp add` cuando está disponible
mcp-aemps install codex
mcp-aemps install vscode           # escribe mcp.servers en settings.json (Copilot Chat MCP)
mcp-aemps install cursor           # escribe ~/.cursor/mcp.json
mcp-aemps install windsurf         # escribe ~/.codeium/windsurf/mcp_config.json
mcp-aemps install zed              # escribe context_servers en Zed settings.json
mcp-aemps install continue         # escribe mcpServers en ~/.continue/config.yaml
mcp-aemps install jetbrains        # escribe ~/.junie/mcp.json (JetBrains Junie)

# URL o nombre de servidor personalizado
mcp-aemps install --url http://my-host:9000/mcp --name aemps

Para desinstalar:

mcp-aemps uninstall                  # quitar de todos
mcp-aemps uninstall claude-desktop   # solo un cliente

Propiedades — los instaladores son idempotentes (se pueden re-ejecutar con seguridad), aditivos (preservan tus otras entradas), atómicos (la escritura se completa entera o no se aplica) y port-aware (leen el puerto real al que se ha bindeado mcp-aemps up, así que puedes cambiar de puerto sin re-instalar).

Rutas de configuración por SO:

Tras instalar, arranca el servidor (puerto por defecto: 8765 — elegido para evitar colisiones con los típicos 8000/5000/3000):

mcp-aemps up           # foreground
mcp-aemps up --daemon  # background
mcp-aemps up --port 9000  # puerto explícito; auto-fallback habilitado por defecto

Después reinicia tu cliente. mcp-aemps aparece como un servidor MCP disponible.

Herramientas MCP — Endpoints oficiales CIMA

Todas las herramientas mapean 1:1 a endpoints REST CIMA oficialmente documentados.

Los problemas de suministro implementan resolución dual-channel: v2 por CN (enriquecida: estado de autorización, flag de comercialización) con fallback automático a v1 por compatibilidad.

Ciclo de vida de los datos

• Sin ficheros locales requeridos. Todos los datos se obtienen de la API CIMA bajo demanda.
• Cache Redis (opcional): warm-up de catálogos maestros al arranque, refresco automático cada 24h sin reiniciar la aplicación.
• Resolución CN → nregistro vía GET /presentacion/:cn (siempre actual, sin datos locales obsoletos).
• Fallback elegante a cache en memoria cuando Redis no está disponible.

Configuración

Todas las opciones se configuran vía variables de entorno:

Observabilidad

Incluye observabilidad in-process ligera — sin requerir collector externo:

• Liveness en /health/live — proceso vivo (siempre 200 si el event loop responde).
• Readiness en /health/ready — backend de cache alcanzable Y warmup de maestras completado (devuelve 503 durante el arranque). Conectar a readinessProbe de Kubernetes.
• Snapshot combinado en /health — JSON {status, version, cache} (mantenido por compatibilidad).
• Métricas in-process en /internal/metrics — JSON {requests_total, requests_by_path, status_codes, errors_5xx, uptime_seconds}. Establece METRICS_KEY para requerir la cabecera X-Metrics-Key.
• Logging estructurado stdlib con rotación diaria + retención gzip.

Para tracing OpenTelemetry o exposición Prometheus, reemplaza el middleware de métricas vía los puntos de extensión extra_middleware / startup_hooks del factory (ver app/factory.py).

Idioma (i18n)

Las strings LLM-facing (descripciones de tools, system prompt, descripciones y bodies de prompts) se entregan en español (default) e inglés. Cambia con la variable MCP_AEMPS_LOCALE:

# Default — auto-detectado del SO; sin variable → es
uvx mcp-aemps stdio

# Inglés explícito (siempre gana sobre el sniff del SO)
MCP_AEMPS_LOCALE=en uvx mcp-aemps stdio

Auto-detección del idioma del sistema operativo ($LC_ALL / $LANG / $LANGUAGE): sistemas en inglés reciben en, todo lo demás (incluyendo locale POSIX C y locales no reconocidos) cae a es porque la fuente de datos CIMA es española. Una MCP_AEMPS_LOCALE explícita siempre gana sobre la auto-detección.

Desde v0.2.9 el catálogo completo de prompts (descripciones + bodies + disclaimer dirigido a pacientes) se entrega en ambos idiomas. Ambos locales registran los mismos 10 nombres de prompt con las mismas signaturas — los clientes que hardcodean nombres siguen funcionando al cambiar de idioma.

OAuth 2.1 (opt-in)

mcp-aemps es público por defecto porque CIMA es público. Para despliegues SaaS multi-tenant o cualquier setup donde necesites gating de acceso, el servidor se puede activar en modo OAuth 2.1 Resource-Server con cinco variables de entorno:

export OAUTH_ENABLED=true
export OAUTH_ISSUER=https://auth.example.com
export OAUTH_JWKS_URL=https://auth.example.com/.well-known/jwks.json
export OAUTH_AUDIENCE=https://mcp-aemps.example.com/mcp
export OAUTH_REQUIRED_SCOPES=mcp:read

Cuando está habilitado:

• Cada llamada a tool MCP sobre HTTP en /mcp requiere un JWT Bearer válido firmado por el Authorization Server configurado.
• El documento PRM se publica en /.well-known/oauth-protected-resource (RFC 9728), de modo que cualquier cliente MCP spec-compliant puede descubrir el AS vía Dynamic Client Registration (RFC 7591).
• stdio no se ve afectado — el acceso process-local se controla por permisos de SO, no por OAuth.

Sin Authorization Server embebido. Apunta OAUTH_ISSUER a cualquier IdP existente — Auth0, Stytch, Cloudflare Workers OAuth Provider, Hydra, Keycloak, etc. mcp-aemps es stateless: verifica tokens, nunca los emite.

Validado end-to-end en v0.2.10: POST /mcp sin token devuelve 401 con cabecera WWW-Authenticate: Bearer error="invalid_token", resource_metadata="<URL del PRM>" (RFC 6750 §3 + RFC 9728).

Anotaciones de Tools

Cada herramienta CIMA se entrega con las anotaciones MCP que los clientes spec-compliant (Claude Desktop, ChatGPT Dev Mode, Cursor, Continue, Zed, JetBrains Junie, …) usan para su UI de auto-aprobación:

Esto hace que los clientes que respetan la spec no pidan confirmación en cada query CIMA — solo gatean llamadas donde las anotaciones lo justifican. Para Claude Code en concreto, ver más abajo cómo construir tus propias confirmation gates independientemente de las anotaciones.

Recursos MCP curados

mcp-aemps expone 5 recursos estáticos + 6 templates bajo el esquema URI cima://. Los recursos son URIs read-only que los clientes MCP pueden streamear y cachear sin pagar el coste en tokens de una llamada a tool — la fuente dominante de gasto de tokens en sesiones interactivas.

Recursos estáticos (auto-descubribles vía resources/list)

Templates (resources/templates/list)

Disponibles en ambos transportes (stdio y /mcp HTTP) — desde v0.2.7 existe un único FastMCP server que sirve tools, prompts y resources para los dos lados.

Prompts MCP curados

mcp-aemps entrega 10 Prompts MCP curados — plantillas de workflow definidas en el servidor que invocas explícitamente desde tu cliente MCP (Claude Desktop, Continue, Cursor, Zed, …). Orquestan las llamadas correctas a tools CIMA para los workflows profesionales y de paciente más comunes, así no tienes que recordar qué tools encadenar.

Disponibilidad en transportes: los prompts se entregan en ambos transportes — stdio (uvx mcp-aemps stdio) y Streamable HTTP en /mcp. Desde v0.2.7 el transporte HTTP usa la app Streamable-HTTP nativa de FastMCP (sin indirección de fastapi-mcp), de modo que tools, prompts, resources y annotations se sirven todos desde la misma instancia FastMCP.

Catálogo

Cómo se invoca

En Claude Desktop (cuando el cliente lo soporta), aparecen como slash-commands /mcp__mcp-aemps__<nombre> en el menú de prompts, o se pueden listar via prompts/list desde cualquier cliente MCP-compliant.

Ejemplo programático con el SDK MCP de Python:

from mcp.client.stdio import stdio_client, StdioServerParameters
from mcp import ClientSession

params = StdioServerParameters(command="uvx", args=["mcp-aemps", "stdio"])
async with stdio_client(params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        prompts = await session.list_prompts()
        result = await session.get_prompt(
            "identificar_cn",
            arguments={"cn": "12345"},
        )
        # result.messages[0].content.text → el cuerpo del prompt listo para enviar al LLM

Diseño

Cada prompt instruye al LLM qué herramientas llamar, en qué orden y cómo formatear la salida. Aprovechan la riqueza del payload de obtener_medicamento (que incluye docs[] con Ficha Técnica, Prospecto, Informe Público de Evaluación y Plan de Gestión de Riesgos; fotos[] con la caja y la forma farmacéutica; el flag materialesInf para vídeos vía obtener_materiales) en lugar de tratar CIMA como un simple lookup de campos.

Los prompts dirigidos a pacientes (material_visual_paciente, info_medicamento_para_no_sanitarios, comprobar_interaccion_principios_activos) cierran siempre con un disclaimer explícito "no es consejo médico — consulte a su médico o farmacéutico". Está cubierto por test (tests/test_prompts.py); su eliminación accidental rompe CI.

Integración con Claude Code hooks

El sistema de hooks de Claude Code ejecuta comandos shell client-side alrededor de cada invocación de tool, incluyendo llamadas a servidores MCP como mcp-aemps. El matcher mcp__mcp-aemps__* captura cada herramienta expuesta por este servidor. Dos recetas concretas para añadir a ~/.claude/settings.json:

1 · Auditar cada llamada mcp-aemps a un log JSONL

Útil para audit trails GMP Annex 11 / EMA GVP — registro completo de qué tool se invocó con qué argumentos, cuándo, en qué sesión.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__mcp-aemps__.*",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{ts: now, session: .session_id, tool: .tool_name, args: .tool_input}' >> ~/.claude/audit/mcp-aemps.jsonl"
          }
        ]
      }
    ]
  }
}

El hook recibe la llamada de tool como JSON por stdin; jq la aplana a una línea por llamada. Rota ~/.claude/audit/ con logrotate o tu agente SIEM.

2 · Enviar latencia por tool a un SIEM

Empareja PreToolUse (start del timer) con PostToolUse (stop del timer) y haz POST del delta más el nombre de tool a tu endpoint de ingest del SIEM.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__mcp-aemps__.*",
        "hooks": [
          { "type": "command", "command": "date +%s%N > /tmp/mcp-aemps.start" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "mcp__mcp-aemps__.*",
        "hooks": [
          {
            "type": "command",
            "command": "END=$(date +%s%N); START=$(cat /tmp/mcp-aemps.start); ELAPSED_MS=$(( (END - START) / 1000000 )); jq -c --arg ms \"$ELAPSED_MS\" '{ts: now, tool: .tool_name, latency_ms: ($ms|tonumber), success: (.tool_response.error == null)}' | curl -sS -X POST -H 'content-type: application/json' --data-binary @- https://siem.example.com/ingest/mcp"
          }
        ]
      }
    ]
  }
}

Equivalente server-side. mcp-aemps también expone pre_tool_hooks / post_tool_hooks en create_app(...) de modo que el mismo audit trail puede emitirse server-side independientemente del cliente MCP que se conecte (útil para despliegues compartidos donde no puedes confiar en que cada usuario tenga el ~/.claude/settings.json correcto). Ver app/tool_hooks.py.

Seguridad

• Usuario Docker non-root (UID 10001)
• Cabeceras de seguridad: X-Frame-Options, X-Content-Type-Options, Referrer-Policy
• pyjwt[crypto] — sin python-jose (CVE-2024-33663)
• Sin secretos en repo — toda configuración via env vars
• CORS configurable, no * en producción

Documentación de referencia

Documentos AEMPS oficiales en docs/:

• CIMA_REST_API.pdf — CIMA REST API v1.23
• CIMA-problemas-suministro.pdf — API de Problemas de Suministro (AEMPS / Ministerio de Sanidad)

Licencia

Apache-2.0 © Román Pérez Dumpert

mcp-name: io.github.romanpert/mcp-aemps