MedLookup

A medical terminology MCP server that provides instant lookups for abbreviations, conditions, drugs, and clinical definitions. Runs in Docker and connects to any MCP-compatible client.

What It Does

lookup_keyword — Search one or more medical keywords across all sources at once:

• 4,600+ medical abbreviations and acronyms (ABG, CBC, COPD, etc.)
• NLM conditions database and ICD-10 diagnosis codes
• MedlinePlus health topic summaries
• Drug information via RxNorm (formulations, classifications) and OpenFDA (indications, dosage, warnings, interactions, mechanism of action)
• UMLS medical concepts and definitions (optional, requires free API key)

add_new_keyword — Save a missing abbreviation or term definition to the local database for future lookups.

remove_keyword — Remove a custom-added entry from the local database. Only deletes entries added via add_new_keyword — built-in abbreviations from the seeded database are protected.

Quick Start

1. Clone and configure

git clone https://github.com/hypersniper05/MCP-MedLookup.git
cd MCP-MedLookup
cp .env.example .env

Edit .env to add your UMLS API key (optional — everything else works without it):

UMLS_API_KEY=your_key_here   # Free at https://uts.nlm.nih.gov/uts/profile

2. Build and run

docker compose up --build -d

The server starts on http://localhost:8010/mcp.

3. Connect your MCP client

Add this to your MCP client configuration (Claude Desktop, Claude Code, etc.):

{
  "mcpServers": {
    "med_lookup": {
      "type": "streamable-http",
      "url": "http://localhost:8010/mcp"
    }
  }
}

Usage Examples

Once connected, your AI assistant can use the tools directly:

"What does ABG stand for?" → Queries lookup_keyword with ["ABG"] — returns "Arterial blood gas"

"Look up metformin and diabetes" → Queries lookup_keyword with ["metformin", "diabetes"] — returns drug info (formulations, FDA label, drug class) and condition info (ICD-10 codes, clinical definitions)

"Add ROSC as an abbreviation meaning Return of Spontaneous Circulation" → Calls add_new_keyword to save it locally

"Remove the ROSC abbreviation I added" → Calls remove_keyword to delete it (only works for custom-added entries)

Data Sources

Source	What It Provides	API Key
imantsm/medical_abbreviations	4,600+ abbreviations seeded into SQLite at build time	None
NLM Clinical Tables	Conditions, ICD-10 codes	None
MedlinePlus	Consumer-friendly health topic summaries	None
RxNorm	Drug formulations, classifications	None
OpenFDA	Full prescribing information (indications, dosage, warnings, interactions)	None
UMLS	Concept definitions across medical vocabularies	Free key

Architecture

server.py              # All MCP tools and server logic (single file)
scripts/seed_db.py     # CSV-to-SQLite import (runs during Docker build)
Dockerfile
docker-compose.yml
requirements.txt
.env.example

The server is a single Python file using FastMCP with Streamable HTTP transport. Abbreviation data is cloned from GitHub and seeded into SQLite during the Docker build. External APIs are queried at runtime with graceful degradation — if any source fails, results from other sources are still returned.

Environment Variables

Variable	Required	Default	Description
UMLS_API_KEY	No	—	Enables UMLS concept lookups (get a free key)
MCP_HOST	No	0.0.0.0	Server bind address
MCP_PORT	No	8010	Server port
DATABASE_PATH	No	/app/data/medical.db	SQLite database path

Docker Commands

docker compose up --build -d     # Build and start
docker compose logs -f           # View logs
docker compose down              # Stop
docker compose up --build -d     # Rebuild after code changes

Verifying the Server

# Check the endpoint
curl http://localhost:8010/mcp

# Interactive testing with MCP Inspector
npx @modelcontextprotocol/inspector
# Connect to: http://localhost:8010/mcp

System Prompt Examples

Example system prompts for configuring your AI assistant to use these tools effectively:

• Detailed — Full prompt with step-by-step research workflow, multi-step examples, and search rules. Best for larger models with thinking enabled.
• Simple — Compact, to-the-point prompt covering all 3 tools and core rules. Best for smaller or faster models.

Tech Stack

• Python 3.12 with FastMCP, httpx, Pydantic
• SQLite for local abbreviation and custom term storage
• Docker with volume-persisted database

License

MIT