omop_mcp

The OMOP MCP Server provides an agentic workflow to map clinical terminology to OMOP concepts using an LLM-backed reasoning loop and vocabulary lookups via OMOP HUB. It exposes tools for free-text to OMOP concept mapping, direct vocabulary search, batch processing from CSV, and automatic prioritization of vocabularies depending on the domain (e.g., LOINC for measurements, SNOMED for conditions). To use it, start the server through the uv runtime as described in installation, ensure you have an OMOP HUB API key for vocabulary lookups, and provide an LLM provider API key for the language model. Once running, you can query the agent with prompts that specify the target OMOP table and field, and optionally attach context such as table names or the target domain. The agent can perform single-term mappings, batch mappings from CSV, and retrieve live documentation from the OMOP CDM resources.

Key capabilities include:

• Vocabulary Search: find_omop_concept enables direct lookup of OMOP concepts via the vocabulary API.
• Mapping Assistance: intelligent mapping of free-text terms to standardized OMOP concepts with rationale.
• Batch Processing: process multiple terms from CSV for bulk mappings.
• Preferred Vocabularies: automatic prioritization of vocabularies by domain to improve relevance.
• Live Documentation: access to current OMOP CDM documentation for reference during mapping.

Prerequisites:

• uv (Universal Viewer) installed on your system. Install from: https://docs.astral.sh/uv/getting-started/installation/
• git
• Access to OMOP HUB API key and an LLM provider API key

Installation steps:

1. Clone the repository: git clone https://github.com/OHNLP/omop_mcp.git cd omop_mcp

2. Install dependencies (via uv runtime configuration as described in README):

   • Ensure uv is installed and accessible in your PATH.

3. Prepare environment variables:

   • Copy the template env file if provided to .env and fill in credentials. The server expects at least an OMOPHUB_API_KEY and an LLM provider API key.
   • Example (in .env or environment): OMOPHUB_API_KEY=your_omophub_api_key LLM_PROVIDER_API_KEY=your_llm_provider_api_key

4. Configure MCP for your Claude Desktop (example from README):

   • In claude_desktop_config.json, set the omop_mcp server: { "mcpServers": { "omop_mcp": { "command": "uv", "args": ["--directory", "<path-to-local-repo>", "run", "omop_mcp"] } } }

5. Run the MCP server via uv (adjust path to local repo as needed): uv --directory <path-to-local-repo> run omop_mcp

6. Verify operation:

   • Open your client (Claude Desktop or other MCP client) and point to the configured MCP server. Provide prompts that specify the target OMOP table and field to map terms to, or use batch tools for CSV inputs.

Notes and tips:

• Ensure the OMOP HUB API key is valid for vocabulary lookups; without it, vocabulary search features will be limited.
• The LLM provider key is required for reasoning and mapping generation; switch providers if you encounter rate limits or cost concerns.
• If you modify the repository locally, update the path in the MCP configuration to reflect the new <path-to-local-repo>.
• For batch processing, prepare a CSV with the terms you want to map and use the provided batch tool to generate mappings in bulk.
• If you encounter connectivity or API errors, verify network access and that environment variables are correctly loaded by the uv runtime.
• Documentation is accessible from the live OMOP CDM and OMOP HUB endpoints; use the live documentation feature to stay up to date with concept definitions.