OMOPHub MCP Server Medical vocabularies for AI agents. Search, map, and navigate 10M+ OMOP concepts: SNOMED CT, ICD-10, RxNorm, LOINC, and more. Directly from Claude, Cursor, VS Code, or any MCP-compatible client. Quick Start · Examples · 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. Ev
Add this skill
npx mdskills install OMOPHub/omophub-mcpComprehensive MCP server providing rich medical vocabulary tools with excellent documentation and examples.
1<h1>OMOPHub MCP Server</h1>23<p>4 <strong>Medical vocabularies for AI agents.</strong><br/>5 Search, map, and navigate 10M+ OMOP concepts: SNOMED CT, ICD-10, RxNorm, LOINC, and more. Directly from Claude, Cursor, VS Code, or any MCP-compatible client.6</p>78<p>9 <a href="https://www.npmjs.com/package/@omophub/omophub-mcp"><img src="https://img.shields.io/npm/v/@omophub/omophub-mcp?style=flat-square&color=cb3837&label=npm" alt="npm version" /></a>10 <a href="https://www.npmjs.com/package/@omophub/omophub-mcp"><img src="https://img.shields.io/npm/dm/@omophub/omophub-mcp?style=flat-square&color=blue" alt="npm downloads" /></a>11 <a href="https://github.com/OMOPHub/omophub-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/OMOPHub/omophub-mcp?style=flat-square" alt="License" /></a>12 <a href="https://github.com/OMOPHub/omophub-mcp"><img src="https://img.shields.io/badge/TypeScript-5.x-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>13 <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green?style=flat-square" alt="MCP Compatible" /></a>14</p>1516<p>17 <a href="#quick-start">Quick Start</a> ·18 <a href="#available-tools">Tools</a> ·19 <a href="#example-prompts">Examples</a> ·20 <a href="https://docs.omophub.com">Docs</a> ·21 <a href="https://omophub.com">Website</a>22</p>2324---2526## Why OMOPHub MCP?2728Working 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.2930**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.3132```33You: "Map ICD-10 code E11.9 to SNOMED"3435Claude: Found it - E11.9 (Type 2 diabetes mellitus without complications)36 maps to SNOMED concept 201826 (Type 2 diabetes mellitus)37 via standard 'Maps to' relationship.38```3940**Use cases:**41- **Concept lookup** - Find OMOP concept IDs for clinical terms in seconds42- **Cross-vocabulary mapping** - Map between ICD-10, SNOMED, RxNorm, LOINC, and 100+ vocabularies43- **Hierarchy navigation** - Explore ancestors and descendants for phenotype definitions44- **Concept set building** - Let your AI agent assemble complete concept sets for cohort definitions45- **Code validation** - Verify medical codes and check their standard mappings4647---4849## Quick Start5051### 1. Get an API Key5253Sign up at [omophub.com](https://omophub.com) → create an API key in your [dashboard](https://dashboard.omophub.com/api-keys).5455### 2. Add to Your AI Client5657<details open>58<summary><strong>Claude Desktop</strong></summary>5960Open Claude Desktop settings > "Developer" tab > "Edit Config". Add to `claude_desktop_config.json`:6162```json63{64 "mcpServers": {65 "omophub": {66 "command": "npx",67 "args": ["-y", "@omophub/omophub-mcp"],68 "env": {69 "OMOPHUB_API_KEY": "oh_your_key_here"70 }71 }72 }73}74```7576</details>7778<details>79<summary><strong>Claude Code</strong></summary>8081```bash82claude mcp add omophub -- npx -y @omophub/omophub-mcp83# Then set OMOPHUB_API_KEY in your environment84```8586</details>8788<details>89<summary><strong>Cursor</strong></summary>9091Open the command palette and choose "Cursor Settings" > "MCP" > "Add new global MCP server". Add to `.cursor/mcp.json`:9293```json94{95 "mcpServers": {96 "omophub": {97 "command": "npx",98 "args": ["-y", "@omophub/omophub-mcp"],99 "env": {100 "OMOPHUB_API_KEY": "oh_your_key_here"101 }102 }103 }104}105```106107</details>108109<details>110<summary><strong>VS Code</strong></summary>111112Add to `.vscode/mcp.json`:113114```json115{116 "servers": {117 "omophub": {118 "command": "npx",119 "args": ["-y", "@omophub/omophub-mcp"],120 "env": {121 "OMOPHUB_API_KEY": "oh_your_key_here"122 }123 }124 }125}126```127128</details>129130<details>131<summary><strong>Streamable HTTP (Remote / Hosted)</strong></summary>132133Run the MCP server as an HTTP service that clients connect to via URL:134135```bash136# Start HTTP server on port 3100137npx -y @omophub/omophub-mcp --transport=http --port=3100 --api-key=oh_your_key_here138139# MCP endpoint: http://localhost:3100/mcp140# Health check: http://localhost:3100/health141```142143Connect MCP clients to `/` or `/mcp`. Useful for centralized deployments where multiple AI agents share one server instance.144145</details>146147<details>148<summary><strong>Hosted (mcp.omophub.com)</strong></summary>149150Connect directly to the OMOPHub-hosted MCP server - no installation required. Each client authenticates with their own API key via the `Authorization` header:151152**Claude Code:**153```bash154claude mcp add omophub --transport http \155 -H "Authorization: Bearer oh_your_key_here" \156 https://mcp.omophub.com157```158159**VS Code** (`.vscode/mcp.json`):160```json161{162 "servers": {163 "omophub": {164 "type": "http",165 "url": "https://mcp.omophub.com",166 "headers": { "Authorization": "Bearer oh_your_key_here" }167 }168 }169}170```171172**Cursor / Windsurf:**173```json174{175 "mcpServers": {176 "omophub": {177 "url": "https://mcp.omophub.com",178 "headers": { "Authorization": "Bearer oh_your_key_here" }179 }180 }181}182```183184> **Note:** Claude Desktop's Custom Connectors UI only supports OAuth and cannot send custom headers. Use the [npx setup](#claude-desktop) instead.185186</details>187188<details>189<summary><strong>Docker</strong></summary>190191```bash192# HTTP mode (default in Docker) - serves MCP on port 3100193docker run -e OMOPHUB_API_KEY=oh_your_key_here -p 3100:3100 omophub/omophub-mcp194195# Stdio mode (for piping)196docker run -i -e OMOPHUB_API_KEY=oh_your_key_here omophub/omophub-mcp --transport=stdio197```198199</details>200201### 3. Start Asking202203> "What's the OMOP concept ID for type 2 diabetes?"204205> "Map ICD-10 code E11.9 to SNOMED"206207> "Show me all descendants of Diabetes mellitus in SNOMED"208209---210211## Available Tools212213| Tool | What it does |214| :--- | :--- |215| `search_concepts` | Search for medical concepts by name or clinical term across all vocabularies |216| `get_concept` | Get detailed info about a specific OMOP concept by `concept_id` |217| `get_concept_by_code` | Look up a concept using a vocabulary-specific code (e.g., ICD-10 `E11.9`) |218| `map_concept` | Map a concept to equivalent concepts in other vocabularies |219| `get_hierarchy` | Navigate concept hierarchy - ancestors, descendants, or both |220| `list_vocabularies` | List available medical vocabularies with statistics |221| `semantic_search` | Search using natural language with neural embeddings (understands clinical meaning) |222| `find_similar_concepts` | Find concepts similar to a reference concept, name, or description |223| `explore_concept` | Get concept details, hierarchy, and cross-vocabulary mappings in one call |224| `fhir_resolve` | Resolve a FHIR coded value (system URI + code) to its OMOP standard concept and CDM target table |225| `fhir_resolve_codeable_concept` | Resolve a FHIR CodeableConcept — picks the best match per OHDSI vocabulary preference |226227### Resources228229| URI | Description |230| :--- | :--- |231| `omophub://vocabularies` | Full vocabulary catalog with statistics |232| `omophub://vocabularies/{vocabulary_id}` | Details for a specific vocabulary |233234### Prompts235236| Prompt | Description |237| :--- | :--- |238| `phenotype-concept-set` | Guided workflow to build a concept set for a clinical phenotype |239| `code-lookup` | Look up and validate a medical code with mappings and hierarchy |240241---242243## Example Prompts244245**Find a concept →** `search_concepts`246> "Search for metformin in RxNorm"247248**Cross-vocabulary mapping →** `map_concept`249> "I have SNOMED concept 201826 - what's the ICD-10 code?"250251**Build a concept set →** `search_concepts` → `get_hierarchy` → `map_concept`252> "Help me build a concept set for Type 2 diabetes including all descendants"253254**Validate a code →** `get_concept_by_code` → `map_concept`255> "Is ICD-10 code E11.9 valid? What does it map to in SNOMED?"256257**Semantic search →** `semantic_search`258> "Find concepts related to 'heart attack'"259260**Explore a concept →** `explore_concept`261> "Give me everything about SNOMED concept 201826"262263**FHIR-to-OMOP resolution →** `fhir_resolve`264> "Resolve FHIR SNOMED code 44054006 to OMOP — what table does it go in?"265266**CodeableConcept →** `fhir_resolve_codeable_concept`267> "This CodeableConcept has both SNOMED 44054006 and ICD-10 E11.9 — which should I use for OMOP?"268269**Find similar →** `find_similar_concepts`270> "What concepts are similar to 'Type 2 diabetes mellitus'?"271272---273274## Configuration275276### Environment Variables277278| Variable | Required | Description |279| :--- | :---: | :--- |280| `OMOPHUB_API_KEY` | ✅ | Your OMOPHub API key |281| `OMOPHUB_BASE_URL` | | Custom API base URL (default: `https://api.omophub.com/v1`) |282| `OMOPHUB_LOG_LEVEL` | | `debug` · `info` · `warn` · `error` (default: `info`) |283| `OMOPHUB_ANALYTICS_OPTOUT` | | Set to `true` to disable analytics headers |284| `MCP_TRANSPORT` | | `stdio` (default) or `http` |285| `MCP_PORT` | | HTTP server port (default: `3100`, only used with `http` transport) |286| `HEALTH_PORT` | | Port for standalone health endpoint in stdio mode (default: disabled) |287288### CLI Arguments289290```bash291# Stdio mode (default)292npx @omophub/omophub-mcp --api-key=oh_your_key --base-url=https://custom.api.com/v1293294# HTTP mode295npx @omophub/omophub-mcp --transport=http --port=3100 --api-key=oh_your_key296297# Stdio mode with standalone health endpoint298npx @omophub/omophub-mcp --api-key=oh_your_key --health-port=8080299```300301### Health Endpoint (Docker / Kubernetes)302303In **HTTP mode**, the health endpoint is available at `/health` on the same port as the MCP endpoint:304305```bash306npx @omophub/omophub-mcp --transport=http --port=3100 --api-key=oh_your_key307curl http://localhost:3100/health308# → {"status":"ok","version":"1.3.1","uptime_seconds":42}309```310311In **stdio mode**, use `--health-port` for a standalone health endpoint:312313```bash314HEALTH_PORT=8080 OMOPHUB_API_KEY=oh_your_key npx @omophub/omophub-mcp315curl http://localhost:8080/health316```317318The Docker image defaults to HTTP mode on port 3100 with health checks built in.319320---321322## Development323324```bash325git clone https://github.com/OMOPHub/omophub-mcp.git326cd omophub-mcp327npm install328npm run build329npm test330```331332Run locally:333334```bash335OMOPHUB_API_KEY=oh_your_key npx tsx src/index.ts336```337338---339340## Troubleshooting341342| Error | Solution |343| :--- | :--- |344| `API key required` | Set `OMOPHUB_API_KEY` in your environment or MCP config |345| `Authentication failed` | API key may be invalid or expired - [generate a new one](https://dashboard.omophub.com/api-keys) |346| `Rate limit exceeded` | Automatic retries are built in. For higher limits, [upgrade your plan](https://dashboard.omophub.com/billing) |347| Tools not appearing | Restart your AI client, verify `npx @omophub/omophub-mcp` runs without errors, check config path |348349---350351## Links352353- [Documentation](https://docs.omophub.com)354- [Get an API Key](https://dashboard.omophub.com/api-keys)355- [Python SDK](https://github.com/OMOPHub/omophub-python)356- [Community & Support](https://github.com/OMOPHub/omophub-mcp/issues)357358---359360## License361362MIT - see [LICENSE](LICENSE)363
Full transparency — inspect the skill content before installing.