OMOP MCP Server

1# OMOP MCP Server
2 
3![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
4[![arXiv](https://img.shields.io/badge/arXiv-2509.03828-b31b1b.svg)](https://arxiv.org/abs/2509.03828)
5 
6Model Context Protocol (MCP) server for mapping clinical terminology to Observational Medical Outcomes Partnership (OMOP) concepts using Large Language Models (LLMs). The vocabulary API is supported by **OMOP HUB**, and you can obtain an API key from [omophub.com](https://omophub.com).
7 
8# Demo Website ([omapper](https://omapper.org))
9 
10![OMapper Screenshot](assets/omapper.png)
11 
12## Overview
13 
14This server provides an agentic framework to standardize medical terms into the OMOP Common Data Model (CDM). It uses the OMOPHub API for vocabulary searching, concept suggestion, and terminology mapping.
15 
16### Installation
17 
18Before configuring the MCP server, ensure you have:
19 
201. **uv** installed on your system
21   - Install from: https://docs.astral.sh/uv/getting-started/installation/
222. Clone the repository
23 
24   ```bash
25   git clone https://github.com/OHNLP/omop_mcp.git
26   cd omop_mcp
27   ```
28 
293. Set up environment variables
30 
31   Copy `.env.template` to `.env` and fill in your API credentials. You will need both an LLM provider key and an **[OMOPHUB_API_KEY](https://omophub.com)** (for vocabulary lookups).
32 
33   ```bash
34   cp .env.template .env
35   ```
36 
37### Configuration for Claude Desktop
38 
39Add the following configuration to your `claude_desktop_config.json` file:
40 
41**Location:**
42 
43- MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
44- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
45 
46**Configuration:**
47 
48Replace `<path-to-local-repo>` with the actual path to your cloned repository.
49 
50```json
51{
52  "mcpServers": {
53    "omop_mcp": {
54      "command": "uv",
55      "args": ["--directory", "<path-to-local-repo>", "run", "omop_mcp"]
56    }
57  }
58}
59```
60 
61## Features
62 
63The OMOP MCP server provides tools and resources for:
64 
65- **Mapping clinical terminology**: Intelligent mapping of free-text terms to standardized OMOP concepts.
66- **Vocabulary Search**: Direct access to OMOP vocabulary via `find_omop_concept`.
67- **Batch Processing**: Tool for mapping multiple concepts from a CSV file.
68- **Preferred Vocabularies**: Automatic domain-specific vocabulary prioritization (e.g., LOINC for measurements, SNOMED for conditions).
69- **Live Documentation**: Resource access to live OMOP CDM documentation.
70 
71## Usage Example
72 
73The agent is most effective when you provide context such as the OMOP table or field name.
74 
75**Prompt:**
76 
77```
78Map `Temperature Temporal Scanner - RR` for `measurement_concept_id` in the `measurement` table.
79```
80 
81**Response Example:**
82 
83```text
84CONCEPT_ID: 46235152
85CODE: 75539-7
86NAME: Body temperature - Temporal artery
87CLASS: Clinical Observation
88CONCEPT: Standard
89VALIDITY: Valid
90DOMAIN: Measurement
91VOCAB: LOINC
92REASON: This LOINC concept specifically represents body temperature measured at the temporal artery.
93URL: https://athena.ohdsi.org/search-terms/terms/46235152
94```
95 
96## Contributing
97 
98See [CONTRIBUTING.md](CONTRIBUTION.md) for guidelines to contribute to the project.
99 
100## Citation Policy
101 
102If you use this software, please cite the pre-print at arXiv (cs.AI) below:
103 
104[An Agentic Model Context Protocol Framework for Medical Concept Standardization](https://arxiv.org/abs/2509.03828)
105 
106## License
107 
108This project is licensed under the Apache License 2.0. See [LICENSE](LICENSE) file for details.
109 
110**Contact:** jaerongahn@gmail.com
111