{
  "markdown": "<h1>OMOPHub MCP Server</h1>\n\n<p>\n  <strong>Medical vocabularies for AI agents.</strong><br/>\n  Search, map, and navigate 11M+ OMOP concepts: SNOMED CT, ICD-10, RxNorm, LOINC, and more. Directly from Claude, Cursor, VS Code, or any MCP-compatible client.\n</p>\n\n<p>\n  <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>\n  <a href=\"https://app.codecov.io/gh/OMOPHub/omophub-mcp?branch=main\"><img src=\"https://codecov.io/gh/OMOPHub/omophub-mcp/branch/main/graph/badge.svg\" alt=\"Codecov\" /></a>\n  <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>\n  <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>\n  <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>\n  <a href=\"https://modelcontextprotocol.io\"><img src=\"https://img.shields.io/badge/MCP-compatible-green?style=flat-square\" alt=\"MCP Compatible\" /></a>\n</p>\n\n<p>\n  <a href=\"#quick-start\">Quick Start</a> ·\n  <a href=\"#available-tools\">Tools</a> ·\n  <a href=\"#example-prompts\">Examples</a> ·\n  <a href=\"https://docs.omophub.com\">Docs</a> ·\n  <a href=\"https://omophub.com\">Website</a>\n</p>\n\n---\n\n## Why OMOPHub MCP?\n\nWorking 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.\n\n**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.\n\n```\nYou: \"Map ICD-10 code E11.9 to SNOMED\"\n\nClaude: Found it - E11.9 (Type 2 diabetes mellitus without complications)\n        maps to SNOMED concept 201826 (Type 2 diabetes mellitus)\n        via standard 'Maps to' relationship.\n```\n\n**Use cases:**\n- **Concept lookup** - Find OMOP concept IDs for clinical terms in seconds\n- **Cross-vocabulary mapping** - Map between ICD-10, SNOMED, RxNorm, LOINC, and 120+ vocabularies\n- **Hierarchy navigation** - Explore ancestors and descendants for phenotype definitions\n- **Concept set building** - Let your AI agent assemble complete concept sets for cohort definitions\n- **Code validation** - Verify medical codes and check their standard mappings\n\n---\n\n## Quick Start\n\n### 1. Get an API Key\n\nSign up at [omophub.com](https://omophub.com) → create an API key in your [dashboard](https://dashboard.omophub.com/api-keys).\n\n### 2. Add to Your AI Client\n\n<details open>\n<summary><strong>Claude Desktop</strong></summary>\n\nOpen Claude Desktop settings > \"Developer\" tab > \"Edit Config\". Add to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"omophub\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@omophub/omophub-mcp\"],\n      \"env\": {\n        \"OMOPHUB_API_KEY\": \"oh_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Claude Code</strong></summary>\n\n```bash\nclaude mcp add omophub -- npx -y @omophub/omophub-mcp\n# Then set OMOPHUB_API_KEY in your environment\n```\n\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\nOpen the command palette and choose \"Cursor Settings\" > \"MCP\" > \"Add new global MCP server\". Add to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"omophub\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@omophub/omophub-mcp\"],\n      \"env\": {\n        \"OMOPHUB_API_KEY\": \"oh_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>VS Code</strong></summary>\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"omophub\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@omophub/omophub-mcp\"],\n      \"env\": {\n        \"OMOPHUB_API_KEY\": \"oh_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Streamable HTTP (Remote / Hosted)</strong></summary>\n\nRun the MCP server as an HTTP service that clients connect to via URL:\n\n```bash\n# Start HTTP server on port 3100\nnpx -y @omophub/omophub-mcp --transport=http --port=3100 --api-key=oh_your_key_here\n\n# MCP endpoint: http://localhost:3100/mcp\n# Health check:  http://localhost:3100/health\n```\n\nConnect MCP clients to `/` or `/mcp`. Useful for centralized deployments where multiple AI agents share one server instance.\n\n</details>\n\n<details>\n<summary><strong>Hosted (mcp.omophub.com)</strong></summary>\n\nConnect directly to the OMOPHub-hosted MCP server - no installation required. Each client authenticates with their own API key via the `Authorization` header:\n\n**Claude Code:**\n```bash\nclaude mcp add omophub --transport http \\\n  -H \"Authorization: Bearer oh_your_key_here\" \\\n  https://mcp.omophub.com\n```\n\n**VS Code** (`.vscode/mcp.json`):\n```json\n{\n  \"servers\": {\n    \"omophub\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.omophub.com\",\n      \"headers\": { \"Authorization\": \"Bearer oh_your_key_here\" }\n    }\n  }\n}\n```\n\n**Cursor / Windsurf:**\n```json\n{\n  \"mcpServers\": {\n    \"omophub\": {\n      \"url\": \"https://mcp.omophub.com\",\n      \"headers\": { \"Authorization\": \"Bearer oh_your_key_here\" }\n    }\n  }\n}\n```\n\n> **Note:** Claude Desktop's Custom Connectors UI only supports OAuth and cannot send custom headers. Use the [npx setup](#claude-desktop) instead.\n\n</details>\n\n<details>\n<summary><strong>Docker</strong></summary>\n\n```bash\n# HTTP mode (default in Docker) - serves MCP on port 3100\ndocker run -e OMOPHUB_API_KEY=oh_your_key_here -p 3100:3100 omophub/omophub-mcp\n\n# Stdio mode (for piping)\ndocker run -i -e OMOPHUB_API_KEY=oh_your_key_here omophub/omophub-mcp --transport=stdio\n```\n\n</details>\n\n### 3. Start Asking\n\n> \"What's the OMOP concept ID for type 2 diabetes?\"\n\n> \"Map ICD-10 code E11.9 to SNOMED\"\n\n> \"Show me all descendants of Diabetes mellitus in SNOMED\"\n\n---\n\n## Available Tools\n\n| Tool | What it does |\n| :--- | :--- |\n| `search_concepts` | Search for medical concepts by name or clinical term across all vocabularies |\n| `get_concept` | Get detailed info about a specific OMOP concept by `concept_id` |\n| `get_concept_by_code` | Look up a concept using a vocabulary-specific code (e.g., ICD-10 `E11.9`) |\n| `map_concept` | Map a concept to equivalent concepts in other vocabularies (paginated — see note below) |\n| `get_hierarchy` | Navigate concept hierarchy - ancestors, descendants, or both |\n| `list_vocabularies` | List available medical vocabularies with statistics |\n| `semantic_search` | Search using natural language with neural embeddings (understands clinical meaning) |\n| `find_similar_concepts` | Find concepts similar to a reference concept, name, or description |\n| `explore_concept` | Get concept details, hierarchy, and cross-vocabulary mappings in one call |\n| `fhir_resolve` | Resolve a FHIR coded value (incl. administrative codes via the HL7 FHIR-to-OMOP IG ConceptMaps) to its OMOP standard concept and CDM target table |\n| `fhir_resolve_codeable_concept` | Resolve a FHIR CodeableConcept — best match by OHDSI vocabulary preference, honoring `userSelected` |\n\n### Resources\n\n| URI | Description |\n| :--- | :--- |\n| `omophub://vocabularies` | Full vocabulary catalog with statistics |\n| `omophub://vocabularies/{vocabulary_id}` | Details for a specific vocabulary |\n\n### Prompts\n\n| Prompt | Description |\n| :--- | :--- |\n| `phenotype-concept-set` | Guided workflow to build a concept set for a clinical phenotype |\n| `code-lookup` | Look up and validate a medical code with mappings and hierarchy |\n\n---\n\n## Example Prompts\n\n**Find a concept →** `search_concepts`\n> \"Search for metformin in RxNorm\"\n\n**Cross-vocabulary mapping →** `map_concept`\n> \"I have SNOMED concept 201826 - what's the ICD-10 code?\"\n\n**Build a concept set →** `search_concepts` → `get_hierarchy` → `map_concept`\n> \"Help me build a concept set for Type 2 diabetes including all descendants\"\n\n> **Completeness matters here.** `map_concept` returns one page at a time\n> (`page_size` 1-200, default 100). A widely-used drug ingredient can have well over\n> a thousand NDC mappings, so a single call is a sample, not the answer. Check\n> `has_more` in the response and keep incrementing `page` until it is `false` —\n> otherwise the concept set looks complete while silently missing codes.\n>\n> Use `find_similar_concepts` for exploration, not for this: it is ranked embedding\n> similarity, so it has no notion of set membership and cannot be exhaustive no\n> matter how large `page_size` is.\n\n**Validate a code →** `get_concept_by_code` → `map_concept`\n> \"Is ICD-10 code E11.9 valid? What does it map to in SNOMED?\"\n\n**Semantic search →** `semantic_search`\n> \"Find concepts related to 'heart attack'\"\n\n**Explore a concept →** `explore_concept`\n> \"Give me everything about SNOMED concept 201826\"\n\n**FHIR-to-OMOP resolution →** `fhir_resolve`\n> \"Resolve FHIR SNOMED code 44054006 to OMOP — what table does it go in?\"\n\n**CodeableConcept →** `fhir_resolve_codeable_concept`\n> \"This CodeableConcept has both SNOMED 44054006 and ICD-10 E11.9 — which should I use for OMOP?\"\n\n**Find similar →** `find_similar_concepts`\n> \"What concepts are similar to 'Type 2 diabetes mellitus'?\"\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n| :--- | :---: | :--- |\n| `OMOPHUB_API_KEY` | ✅ | Your OMOPHub API key |\n| `OMOPHUB_BASE_URL` | | Custom API base URL (default: `https://api.omophub.com/v1`) |\n| `OMOPHUB_LOG_LEVEL` | | `debug` · `info` · `warn` · `error` (default: `info`) |\n| `OMOPHUB_ANALYTICS_OPTOUT` | | Set to `true` to disable analytics headers |\n| `OMOPHUB_USER_AGENT_SUFFIX` | | Optional deployment identifier appended to `omophub-mcp/<version>` (default: none) |\n| `MCP_TRANSPORT` | | `stdio` (default) or `http` |\n| `MCP_PORT` | | HTTP server port (default: `3100`, only used with `http` transport) |\n| `HEALTH_PORT` | | Port for standalone health endpoint in stdio mode (default: disabled) |\n\n### CLI Arguments\n\n```bash\n# Stdio mode (default)\nnpx @omophub/omophub-mcp --api-key=oh_your_key --base-url=https://custom.api.com/v1\n\n# HTTP mode\nnpx @omophub/omophub-mcp --transport=http --port=3100 --api-key=oh_your_key\n\n# Stdio mode with standalone health endpoint\nnpx @omophub/omophub-mcp --api-key=oh_your_key --health-port=8080\n```\n\n### Health Endpoint (Docker / Kubernetes)\n\nIn **HTTP mode**, the health endpoint is available at `/health` on the same port as the MCP endpoint:\n\n```bash\nnpx @omophub/omophub-mcp --transport=http --port=3100 --api-key=oh_your_key\ncurl http://localhost:3100/health\n# → {\"status\":\"ok\",\"version\":\"1.5.0\",\"uptime_seconds\":42}\n```\n\nIn **stdio mode**, use `--health-port` for a standalone health endpoint:\n\n```bash\nHEALTH_PORT=8080 OMOPHUB_API_KEY=oh_your_key npx @omophub/omophub-mcp\ncurl http://localhost:8080/health\n```\n\nThe Docker image defaults to HTTP mode on port 3100 with health checks built in.\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/OMOPHub/omophub-mcp.git\ncd omophub-mcp\nnpm install\nnpm run build\nnpm test\n```\n\nRun locally:\n\n```bash\nOMOPHUB_API_KEY=oh_your_key npx tsx src/index.ts\n```\n\n---\n\n## Troubleshooting\n\n| Error | Solution |\n| :--- | :--- |\n| `API key required` | Set `OMOPHUB_API_KEY` in your environment or MCP config |\n| `Authentication failed` | API key may be invalid or expired - [generate a new one](https://dashboard.omophub.com/api-keys) |\n| `Rate limit exceeded` | Automatic retries are built in. For higher limits, [upgrade your plan](https://dashboard.omophub.com/billing) |\n| Tools not appearing | Restart your AI client, verify `npx @omophub/omophub-mcp` runs without errors, check config path |\n\n---\n\n## Links\n\n- [Documentation](https://docs.omophub.com)\n- [Get an API Key](https://dashboard.omophub.com/api-keys)\n- [Python SDK](https://github.com/OMOPHub/omophub-python)\n- [Community & Support](https://github.com/OMOPHub/omophub-mcp/issues)\n\n---\n\n## License\n\nMIT - see [LICENSE](LICENSE)\n",
  "bytes": 12071,
  "sha": "2c85e75ae11127a8d387e8b0dffae82d9fea0e7ead6ba4c163dc61ee0222310f",
  "repo_slug": "omophub/omophub-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_omophub_omophub_mcp_7e36dfd0/readme"
}