mcp-aemps 0.2.5

Open-source MCP server for the Spanish AEMPS CIMA pharmaceutical registry

mcp-aemps

The first open-source, regulatory-compliant MCP server for the pharmaceutical industry.
Real-time access to Spain's AEMPS/CIMA drug registry — 20,000+ authorised medicines, safety alerts, supply problems, clinical documents — as structured MCP tools for any AI assistant.

---

What it does

mcp-aemps wraps the AEMPS CIMA REST API as a full MCP server. Connect Claude, GPT-4o, Gemini — or any MCP-compatible agent — to Spain's official pharmaceutical registry. Query drug authorisations, technical sheets, pharmacovigilance safety notes, supply problems, clinical equivalents, and more, in real time.

Data source: CIMA (AEMPS) — public API, no PII, no authentication required.
Compliance posture: Read-only proxy. Audit trail per request. No patient data processed.

---

Install

# pip
pip install mcp-aemps

# zero-install (recommended for CLI clients)
uvx mcp-aemps up
pipx run mcp-aemps up

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

# Docker Compose
docker compose up -d

---

One-command client setup

After pip install mcp-aemps, register the server with your MCP client in one command — no manual JSON editing.

# All detected clients at once
mcp-aemps install

# Or pick one
mcp-aemps install claude-desktop   # stdio default (uvx auto-launch); HTTP via mcp-remote optional
mcp-aemps install claude-code      # uses `claude mcp add` if available
mcp-aemps install codex
mcp-aemps install vscode           # writes mcp.servers in user settings.json (Copilot Chat MCP)
mcp-aemps install cursor           # writes ~/.cursor/mcp.json
mcp-aemps install windsurf         # writes ~/.codeium/windsurf/mcp_config.json
mcp-aemps install zed              # writes context_servers in Zed settings.json
mcp-aemps install continue         # writes mcpServers in ~/.continue/config.yaml
mcp-aemps install jetbrains        # writes ~/.junie/mcp.json (JetBrains Junie)

# Custom URL or server key
mcp-aemps install --url http://my-host:9000/mcp --name aemps

To remove:

mcp-aemps uninstall                  # remove from all
mcp-aemps uninstall claude-desktop   # one client only

Properties — installers are idempotent (safe to re-run), additive (preserves your other entries), atomic (write succeeds fully or not at all), and port-aware (read the actual port mcp-aemps up bound to, so you can change ports without re-installing).

Per-OS config paths:

Client	macOS	Windows	Linux
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json	%APPDATA%\Claude\claude_desktop_config.json	~/.config/Claude/claude_desktop_config.json
Claude Code	claude mcp add (preferred) → fallback ~/.claude.json	same	same
Codex	~/.codex/config.toml	%USERPROFILE%\.codex\config.toml	~/.codex/config.toml
VS Code	~/Library/Application Support/Code/User/settings.json	%APPDATA%\Code\User\settings.json	~/.config/Code/User/settings.json
Cursor	~/.cursor/mcp.json	same	same
Windsurf	~/.codeium/windsurf/mcp_config.json	same	same
Zed	~/.config/zed/settings.json	%APPDATA%\Zed\settings.json	~/.config/zed/settings.json
Continue.dev	~/.continue/config.yaml	same	same
JetBrains Junie	~/.junie/mcp.json	same	same

After install, start the server (default port: 8765 — chosen to avoid collisions with the very common 8000/5000/3000):

mcp-aemps up           # foreground
mcp-aemps up --daemon  # background
mcp-aemps up --port 9000  # explicit port; auto-fallback enabled by default

Then restart your client. mcp-aemps appears as an available MCP server.

---

MCP Tools — Official CIMA Endpoints

All tools map 1:1 to officially documented CIMA REST API endpoints.

Tool	CIMA Endpoint	Description
obtener_medicamento	GET /medicamento	Full drug record by CN or nregistro
buscar_medicamentos	GET /medicamentos	Filtered/paginated drug search (20+ filters)
buscar_en_ficha_tecnica	POST /buscarEnFichaTecnica	Full-text search inside technical sheets
listar_presentaciones	GET /presentaciones	Presentations list with filters
obtener_presentacion	GET /presentacion/:cn	Presentation detail by National Code
buscar_vmpp	GET /vmpp	Clinical equivalents (VMP/VMPP)
consultar_maestras	GET /maestras	Master catalogs: ATC, active ingredients, forms, labs
registro_cambios	`GET	POST /registroCambios`
problemas_suministro	GET /psuministro + GET /psuministro/v2/cn/:cn	Supply problems — global listing or per National Code
problemas_suministro_dcp	GET /psuministro/v2/dcp/:dcp	Supply problems by DCP (clinical product description)
problemas_suministro_dcpf	GET /psuministro/v2/dcpf/:dcpf	Supply problems by DCPF (with pharmaceutical form)
listar_notas / obtener_notas	GET /notas/:nregistro	Safety notes
listar_materiales / obtener_materiales	GET /materiales/:nregistro	Safety informational materials
doc_secciones	GET /docSegmentado/secciones/:tipo	Technical sheet / leaflet section metadata
doc_contenido	GET /docSegmentado/contenido/:tipo	Section content (JSON / HTML / plain text)
html_ficha_tecnica	GET /dochtml/ft/:nregistro/:file	Full technical sheet HTML
html_prospecto	GET /dochtml/p/:nregistro/:file	Full patient leaflet HTML

Supply problems implement dual-channel resolution: v2 per-CN (enriched: authorization status, comercialisation flag) with automatic fallback to v1 for compatibility.

---

Data Lifecycle

• No local files required. All data fetched from CIMA API on demand.
• Redis cache (optional): startup warm-up for master catalogs (maestras), automatic 24h refresh — no app restart needed.
• CN → nregistro resolution via GET /presentacion/:cn (always current, no stale local data).
• Falls back gracefully to in-memory cache when Redis is unavailable.

---

Configuration

All settings via environment variables:

Variable	Default	Description
PORT	8765	Server port (mcp-aemps up --auto-port finds free if busy)
REDIS_URL	—	Redis or Valkey connection (optional, enables distributed cache + rate limit)
ALLOWED_ORIGINS	http://localhost:3000	CORS origins (do not use * in production)
METRICS_KEY	—	If set, /internal/metrics requires the X-Metrics-Key header. Recommended in production.
LOG_LEVEL	INFO	Logging level
LOG_RETENTION_DAYS	90	Daily-rotated gzipped log retention
MAX_RESULTS	30	Max items per page returned by list endpoints

---

Observability

Ships with lightweight in-process observability — no external collector required:

• Liveness at /health/live — process is alive (always 200 if the event loop responds).
• Readiness at /health/ready — cache backend reachable AND maestras warmup completed (returns 503 during startup). Wire this into Kubernetes readinessProbe.
• Combined snapshot at /health — {status, version, cache} JSON (kept for backwards compatibility).
• In-process metrics at /internal/metrics — {requests_total, requests_by_path, status_codes, errors_5xx, uptime_seconds} JSON. Set METRICS_KEY to require the X-Metrics-Key header.
• Structured stdlib logging with daily rotation + gzip retention

For OpenTelemetry tracing or Prometheus exposition, replace the metrics middleware via the factory's extra_middleware / startup_hooks extension points (see app/factory.py).

---

Tool Annotations

Every CIMA tool ships with the MCP tool annotations that compliant clients (Claude Desktop, ChatGPT Dev Mode, Cursor, Continue, Zed, JetBrains Junie, …) use to drive their auto-approve UI:

Hint	Value	Reason
readOnlyHint	true	The server is a thin proxy — no writes upstream.
destructiveHint	false	No environment mutations, ever.
idempotentHint	true	Same args at the same instant return the same payload.
openWorldHint	true	Tools hit the external CIMA HTTP API.

This means clients that respect the spec will not prompt for confirmation on every CIMA query — they only gate calls where the annotations actually warrant caution. For Claude Code specifically, see the next section to build your own confirmation gates regardless of annotation hints.

---

Integrating with Claude Code hooks

Claude Code's hooks system fires shell commands client-side around every tool invocation, including calls to MCP servers like mcp-aemps. The matcher mcp__mcp-aemps__* catches every tool exposed by this server. Three concrete recipes to drop into ~/.claude/settings.json:

1 · Audit every mcp-aemps call to a JSONL log

Useful for GMP Annex 11 / EMA GVP audit trails — full record of which tool was invoked with which arguments, when, by which session.

{
  "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"
          }
        ]
      }
    ]
  }
}

The hook receives the tool call as JSON on stdin; jq flattens it to one line per call. Rotate ~/.claude/audit/ with logrotate or your SIEM agent.

2 · Gate image downloads behind explicit confirmation

descargar_imagenes returns base64-encoded medication images that can be large and bandwidth-expensive. Block the call unless the user has opted in via an env-var flag.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__mcp-aemps__descargar_imagenes",
        "hooks": [
          {
            "type": "command",
            "command": "[ \"$MCP_AEMPS_ALLOW_IMAGES\" = '1' ] || { echo 'Set MCP_AEMPS_ALLOW_IMAGES=1 to authorise image downloads' >&2; exit 2; }"
          }
        ]
      }
    ]
  }
}

Exit code 2 aborts the tool call and returns the stderr message to the model — Claude Code surfaces it as a denied tool with reason.

3 · Ship per-tool latency to a SIEM

Pair PreToolUse (timer start) with PostToolUse (timer stop) and POST the delta plus tool name to your SIEM ingestion endpoint.

{
  "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"
          }
        ]
      }
    ]
  }
}

Server-side equivalent. mcp-aemps also exposes pre_tool_hooks / post_tool_hooks on create_app(...) so the same audit trail can be emitted server-side regardless of which MCP client is connected (useful for shared deployments where you can't rely on every user having the right ~/.claude/settings.json). See app/tool_hooks.py.

---

Security

• Non-root Docker user (UID 10001)
• Security headers: X-Frame-Options, X-Content-Type-Options, Referrer-Policy
• pyjwt[crypto] — no python-jose (CVE-2024-33663)
• No secrets in repo — all config via env vars
• CORS configurable, not * in production

---

Reference Documentation

Official AEMPS source documents in docs/:

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

---

License

Apache-2.0 © Román Pérez Dumpert

_{^{mcp-name: io.github.romanpert/mcp-aemps}}