📦

io.github.OMOPHub/omophub-mcp

Name: io.github.OMOPHub/omophub-mcp
Rating: 1.9

Search, lookup, map, and navigate OMOP medical vocabularies via AI agents

0 installs

Trust: 37 — Low

Devtools

Ask AI about io.github.OMOPHub/omophub-mcp

I know everything about io.github.OMOPHub/omophub-mcp. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

OMOPHub MCP Server

Medical vocabularies for AI agents.
Search, map, and navigate 5M+ OMOP concepts: SNOMED CT, ICD-10, RxNorm, LOINC, and more. Directly from Claude, Cursor, VS Code, or any MCP-compatible client.

Quick Start · Tools · Examples · Docs · Website

Why OMOPHub MCP?

Working with medical vocabularies today means downloading multi-gigabyte CSV files, loading them into a local database, and writing SQL to find what you need. Every time.

OMOPHub MCP Server gives your AI assistant instant access to the entire OHDSI ATHENA vocabulary. No database setup, no CSV wrangling, no context switching. Just ask.

You: "Map ICD-10 code E11.9 to SNOMED"

Claude: Found it - E11.9 (Type 2 diabetes mellitus without complications)
        maps to SNOMED concept 201826 (Type 2 diabetes mellitus)
        via standard 'Maps to' relationship.

Use cases:

Concept lookup - Find OMOP concept IDs for clinical terms in seconds
Cross-vocabulary mapping - Map between ICD-10, SNOMED, RxNorm, LOINC, and 100+ vocabularies
Hierarchy navigation - Explore ancestors and descendants for phenotype definitions
Concept set building - Let your AI agent assemble complete concept sets for cohort definitions
Code validation - Verify medical codes and check their standard mappings

Quick Start

1. Get an API Key

2. Add to Your AI Client

Claude Desktop

Open Claude Desktop settings > "Developer" tab > "Edit Config". Add to claude_desktop_config.json:

{
  "mcpServers": {
    "omophub": {
      "command": "npx",
      "args": ["-y", "@omophub/omophub-mcp"],
      "env": {
        "OMOPHUB_API_KEY": "oh_your_key_here"
      }
    }
  }
}

Claude Code

claude mcp add omophub -- npx -y @omophub/omophub-mcp
# Then set OMOPHUB_API_KEY in your environment

Cursor

Open the command palette and choose "Cursor Settings" > "MCP" > "Add new global MCP server". Add to .cursor/mcp.json:

{
  "mcpServers": {
    "omophub": {
      "command": "npx",
      "args": ["-y", "@omophub/omophub-mcp"],
      "env": {
        "OMOPHUB_API_KEY": "oh_your_key_here"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "omophub": {
      "command": "npx",
      "args": ["-y", "@omophub/omophub-mcp"],
      "env": {
        "OMOPHUB_API_KEY": "oh_your_key_here"
      }
    }
  }
}

Streamable HTTP (Remote / Hosted)

Run the MCP server as an HTTP service that clients connect to via URL:

# Start HTTP server on port 3100
npx -y @omophub/omophub-mcp --transport=http --port=3100 --api-key=oh_your_key_here

# MCP endpoint: http://localhost:3100/mcp
# Health check:  http://localhost:3100/health

Connect MCP clients to the /mcp endpoint. Useful for centralized deployments where multiple AI agents share one server instance.

Docker

# HTTP mode (default in Docker) — serves MCP on port 3100
docker run -e OMOPHUB_API_KEY=oh_your_key_here -p 3100:3100 omophub/omophub-mcp

# Stdio mode (for piping)
docker run -i -e OMOPHUB_API_KEY=oh_your_key_here omophub/omophub-mcp --transport=stdio

3. Start Asking

"What's the OMOP concept ID for type 2 diabetes?"

"Map ICD-10 code E11.9 to SNOMED"

"Show me all descendants of Diabetes mellitus in SNOMED"

Available Tools

Tool	What it does
`search_concepts`	Search for medical concepts by name or clinical term across all vocabularies
`get_concept`	Get detailed info about a specific OMOP concept by `concept_id`
`get_concept_by_code`	Look up a concept using a vocabulary-specific code (e.g., ICD-10 `E11.9`)
`map_concept`	Map a concept to equivalent concepts in other vocabularies
`get_hierarchy`	Navigate concept hierarchy - ancestors, descendants, or both
`list_vocabularies`	List available medical vocabularies with statistics

Resources

URI	Description
`omophub://vocabularies`	Full vocabulary catalog with statistics
`omophub://vocabularies/{vocabulary_id}`	Details for a specific vocabulary

Prompts

Prompt	Description
`phenotype-concept-set`	Guided workflow to build a concept set for a clinical phenotype
`code-lookup`	Look up and validate a medical code with mappings and hierarchy

Example Prompts

Find a concept → search_concepts

"Search for metformin in RxNorm"

Cross-vocabulary mapping → map_concept

"I have SNOMED concept 201826 - what's the ICD-10 code?"

Build a concept set → search_concepts → get_hierarchy → map_concept

"Help me build a concept set for Type 2 diabetes including all descendants"

Validate a code → get_concept_by_code → map_concept

"Is ICD-10 code E11.9 valid? What does it map to in SNOMED?"

Configuration

Environment Variables

Variable	Required	Description
`OMOPHUB_API_KEY`	✅	Your OMOPHub API key
`OMOPHUB_BASE_URL`		Custom API base URL (default: `https://api.omophub.com/v1`)
`OMOPHUB_LOG_LEVEL`		`debug` · `info` · `warn` · `error` (default: `info`)
`OMOPHUB_ANALYTICS_OPTOUT`		Set to `true` to disable analytics headers
`MCP_TRANSPORT`		`stdio` (default) or `http`
`MCP_PORT`		HTTP server port (default: `3100`, only used with `http` transport)
`HEALTH_PORT`		Port for standalone health endpoint in stdio mode (default: disabled)

CLI Arguments

# Stdio mode (default)
npx @omophub/omophub-mcp --api-key=oh_your_key --base-url=https://custom.api.com/v1

# HTTP mode
npx @omophub/omophub-mcp --transport=http --port=3100 --api-key=oh_your_key

# Stdio mode with standalone health endpoint
npx @omophub/omophub-mcp --api-key=oh_your_key --health-port=8080

Health Endpoint (Docker / Kubernetes)

In HTTP mode, the health endpoint is available at /health on the same port as the MCP endpoint:

npx @omophub/omophub-mcp --transport=http --port=3100 --api-key=oh_your_key
curl http://localhost:3100/health
# → {"status":"ok","version":"1.1.0","uptime_seconds":42}

In stdio mode, use --health-port for a standalone health endpoint:

HEALTH_PORT=8080 OMOPHUB_API_KEY=oh_your_key npx @omophub/omophub-mcp
curl http://localhost:8080/health

The Docker image defaults to HTTP mode on port 3100 with health checks built in.

Development

git clone https://github.com/OMOPHub/omophub-mcp.git
cd omophub-mcp
npm install
npm run build
npm test

Run locally:

OMOPHUB_API_KEY=oh_your_key npx tsx src/index.ts

Troubleshooting

Error	Solution
`API key required`	Set `OMOPHUB_API_KEY` in your environment or MCP config
`Authentication failed`	API key may be invalid or expired - generate a new one
`Rate limit exceeded`	Automatic retries are built in. For higher limits, upgrade your plan
Tools not appearing	Restart your AI client, verify `npx @omophub/omophub-mcp` runs without errors, check config path

License

MIT - see LICENSE