Skip to main content

​
What is the MCP Server?

The OMOPHub MCP Server connects your AI assistant to the entire OHDSI ATHENA vocabulary. No database setup, no CSV wrangling — just ask your AI about medical concepts and get verified answers. 
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.

​
Installation

Install via npm — no build step required: 
npm install -g @omophub/omophub-mcp
Or run directly with npx: 
npx -y @omophub/omophub-mcp

​
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 > 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"
      }
    }
  }
}

​
Windsurf

Add to your Windsurf MCP configuration: 
{
  "mcpServers": {
    "omophub": {
      "command": "npx",
      "args": ["-y", "@omophub/omophub-mcp"],
      "env": {
        "OMOPHUB_API_KEY": "oh_your_key_here"
      }
    }
  }
}

​
Available Tools

ToolDescription
search_conceptsSearch for medical concepts by name or clinical term across all vocabularies
get_conceptGet detailed info about a specific OMOP concept by concept_id
get_concept_by_codeLook up a concept using a vocabulary-specific code (e.g., ICD-10 E11.9)
map_conceptMap a concept to equivalent concepts in other vocabularies
get_hierarchyNavigate concept hierarchy — ancestors, descendants, or both
list_vocabulariesList available medical vocabularies with statistics

Tools Reference

See detailed parameter schemas and examples for each tool.

​
Environment Variables

VariableRequiredDescription
OMOPHUB_API_KEYYesYour OMOPHub API key
OMOPHUB_BASE_URLCustom API base URL (default: https://api.omophub.com/v1)
OMOPHUB_LOG_LEVELdebug · info · warn · error (default: info)
OMOPHUB_ANALYTICS_OPTOUTSet to true to disable analytics headers
MCP_TRANSPORTstdio (default) or http
MCP_PORTHTTP server port (default: 3100, only with http transport)
HEALTH_PORTPort for standalone health endpoint in stdio mode

​
Example Prompts

Try these after installing:
“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”
“Search for metformin in RxNorm”
“Help me build a concept set for heart failure including all descendants”

​
Troubleshooting

ErrorSolution
API key requiredSet OMOPHUB_API_KEY in your environment or MCP config
Authentication failedAPI key may be invalid or expired — generate a new one
Rate limit exceededAutomatic retries are built in. For higher limits, upgrade your plan
Tools not appearingRestart your AI client, verify npx @omophub/omophub-mcp runs without errors