mcp-aemps 0.1.3

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
docker run -p 8000:8000 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
mcp-aemps install claude-code
mcp-aemps install codex

# 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

The installer is idempotent — running it twice is safe — and preserves existing entries in your client config. It edits the right file per OS:

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

After install, start the server (in another terminal or as a background daemon):

mcp-aemps up           # foreground
mcp-aemps up --daemon  # background

Then restart your client. mcp-aemps will appear 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	8000	Server port
REDIS_URL	—	Redis connection (optional, enables caching)
ALLOWED_ORIGINS	http://localhost:3000	CORS origins
METRICS_KEY	—	Auth key for /internal/metrics
LOG_LEVEL	INFO	Logging level
RATE_LIMIT	100	Requests per period
RATE_PERIOD	60	Period in seconds

---

Observability

• Structured JSON logging with correlation IDs per request
• OpenTelemetry tracing (OTLP export)
• Prometheus metrics at /internal/metrics (protected by x-metrics-key)
• Health check at /health

---

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)

---

Full Version

This is the open-source Community Edition. A Full Edition is available with extended capabilities for enterprise and regulated environments.

For licensing, integration support, or custom deployments:

[e-mail]

---

License

Apache-2.0 © Román Pérez Dumpert

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