medical-mcp
An MCP server that provides comprehensive medical information by querying multiple authoritative medical APIs including FDA, WHO, PubMed, Google Scholar, and RxNorm
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/jamesanz--medical-mcp)HTML
<a href="/listings/jamesanz--medical-mcp"><img src="/api/listings/jamesanz--medical-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**Install in Cursor (Recommended):**
[π Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=medical-mcp&config=eyJtZWRpY2FsLW1jcCI6eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1lZGljYWwtbWNwIl19fQ==)
**Or install manually:**
npm install -g medical-mcp # Or from source: git clone https://github.com/JamesANZ/medical-mcp.git cd medical-mcp && npm install && npm run build
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md Β· README Β· 383 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # π©Ί Medical MCP Server
- > **Bring trusted medical data directly into your AI workflow.** A local server for private, free access to FDA, WHO, PubMed, RxNorm, Semantic Scholar, and Google Scholar. No API keys. No data leaks.
- An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that brings authoritative medical information into AI coding environments like Cursor and Claude Desktop.
- <a href="https://glama.ai/mcp/servers/@JamesANZ/medical-mcp">
- <img width="380" height="200" src="https://glama.ai/mcp/servers/@JamesANZ/medical-mcp/badge" alt="medical-mcp MCP server" />
- </a>
- [](https://archestra.ai/mcp-catalog/jamesanz__medical-mcp)
- ## Why Use Medical MCP?
- - π **Your Data Never Leaves** β Runs 100% locally; no tracking, no logs, no cloud
- - π **No API Keys** β Works out of the box, zero configuration
- - π₯ **Authoritative Sources** β FDA, TGA, Health Canada, EMA, DailyMed, WHO, PubMed, RxNorm, ClinicalTrials.gov
- - β‘ **Easy Setup** β One-click install in [Cursor](https://cursor.sh) or simple manual setup
- - π¬ **Comprehensive** β Drug info, health stats, medical literature, clinical guidelines, pediatric sources
- - π‘οΈ **Resilient** β Circuit breakers, retry with backoff, rate limiting, and automatic fallbacks
- - π **Evidence-Graded** β Results tagged with study type and evidence level (Meta-Analysis β Case Report). Tags are automatic labels from the title and abstract, not independently checked grades.
- - π₯ **Health Monitoring** β Built-in health check tool to diagnose source availability
- ## What's New in v2.0
- - **Resilience Layer** β Circuit breakers per source, retry with exponential backoff + jitter, per-source token bucket rate limiters
- - **Monid web search** β Scholar, AAP, and PMC HTML go through Monid TinyFish (Tavily-style search/fetch). Semantic Scholar is the no-key fallback
- - **Evidence Grading** β PubMed and multi-database results tagged with study type (Systematic Review, RCT, Cohort, Case Report, etc.) and evidence grade (IβV). These tags are automatic labels from the title and abstract, not independently checked grades.
- - **Response Validation** β Zod schemas validate all upstream API responses, logging warnings on schema drift without breaking
- - **NCBI API Key Support** β Optional `NCBI_API_KEY` env var boosts PubMed from 3 req/sec to 10 req/sec
- - **Health Check Tool** β `health-check` pings all upstream sources and reports latency, circuit breaker states, rate limiter status, and cache health
- - **Structured Logging** β Leveled, structured logging (DEBUG/INFO/WARN/ERROR) with source tracking and timing for every API call
- - **Request Timeouts** β All upstream calls have explicit response/deadline timeouts to prevent hanging
- ## Quick Start
- **Install in Cursor (Recommended):**
- [π Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=medical-mcp&config=eyJtZWRpY2FsLW1jcCI6eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1lZGljYWwtbWNwIl19fQ==)
- **Or install manually:**
- ```bash
- npm install -g medical-mcp
- # Or from source:
- git clone https://github.com/JamesANZ/medical-mcp.git
- cd medical-mcp && npm install && npm run build
- ```
- ## Features
- ### π Drug Information
- - **`search-drugs`** β Search FDA, DailyMed, TGA (Australia), Health Canada, and EMA. Filter with `countries` (`US`, `AU`, `CA`, `EU`). Unsupported codes are rejected rather than returned as empty regulatory results.
- - **`search-drug-nomenclature`** β Standardized drug names via RxNorm (`limit` defaults to 25)
- - **`search-drug-safety`** β FDA FAERS adverse events (with report IDs), recalls, and shortages
- ### π Health Statistics
- - **`get-health-statistics`** β WHO Global Health Observatory data (life expectancy, mortality, disease prevalence)
- ### π¬ Medical Literature
- - **`search-medical-literature`** β Search 30M+ PubMed articles (with evidence grading). Optional `question` or `rerank` reorders those hits so papers that actually answer the question sit above papers that only share keywords.
- - **`rank-search-hits`** β Same rerank for a list you already have (title + abstract). Retrieval ranking only β not diagnosis or advice.
- - **`get-article-details`** β Detailed article info by PMID
- - **`search-google-scholar`** β Academic papers via Monid TinyFish (`research_paper`) when `MONID_API_KEY` is set; otherwise Semantic Scholar
- - **`search-medical-journals`** β Top journals (NEJM, JAMA, Lancet, BMJ, Nature Medicine)
- ### π₯ Clinical Tools
- - **`search-clinical-guidelines`** β Practice recommendations from medical organizations
- - **`search-clinical-trials`** β ClinicalTrials.gov
- - **`list-sources`** β Full catalog of registry adapters and dedicated-tool sources (WHO, PubMed, RxNorm, Scholar, AAP), including which MCP tool reaches each. This is not the `search-drugs` five-regulator fanout.
- ### πΆ Pediatric Sources
- - **`search-pediatric-guidelines`** β AAP policy/clinical reports via PubMed, plus Bright Futures. Off-domain web hits are dropped; labels come from the page, not from which search ran.
- - **`search-pediatric-literature`** β Research from major pediatric journals. Optional `question` / `rerank` like medical literature.
- - **`search-pediatric-drugs`** β Drugs with pediatric labeling, NDC, manufacturer, and DailyMed URL
- ### π‘οΈ Reliability & Monitoring
- - **`health-check`** β Ping all upstream sources, report latency/status, circuit breaker states, and cache health
- - **`get-cache-stats`** β View cache statistics (hit rate, memory usage, entry count)
- ## Installation
- ### Cursor (One-Click)
- Click the install link above or use:
- ```
- cursor://anysphere.cursor-deeplink/mcp/install?name=medical-mcp&config=eyJtZWRpY2FsLW1jcCI6eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1lZGljYWwtbWNwIl19fQ==
- ```
- ### Manual Installation
- **Requirements:** Node.js 18+ and npm
- ```bash
- git clone https://github.com/JamesANZ/medical-mcp.git
- cd medical-mcp
- npm install
- npm run build
- npm start
- ```
- ### Claude Desktop
- Add to `claude_desktop_config.json`:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- ```json
- {
- "mcpServers": {
- "medical-mcp": {
- "command": "node",
- "args": ["/absolute/path/to/medical-mcp/build/index.js"],
- "env": {
- "NCBI_API_KEY": "your_optional_key_here"
- }
- }
- }
- }
- ```
- Restart Claude Desktop after configuration.
- ### Docker
- The container runs the HTTP server. It listens on port 3000 inside the container. `-p 3000:3000` publishes that port on your machine. Optional API keys are passed at run time and are not written into the image.
- ```bash
- docker build -t medical-mcp:local .
- docker run --name medical-mcp --rm -p 3000:3000 medical-mcp:local
- ```
- If something on the machine is already listening on port 3000, publish a different host port and point the client at that port. The process inside the container still uses 3000.
- ```bash
- docker run --name medical-mcp --rm -p 3010:3000 medical-mcp:local
- ```
- In another terminal:
- ```bash
- docker logs medical-mcp
- docker stop medical-mcp
- ```
- `docker stop` sends SIGTERM. The process stops accepting connections and exits.
- Point an MCP client at `http://127.0.0.1:3000/mcp`. A health URL is not an MCP session. The client has to send `initialize` and then `tools/call`.
- Pass an optional key from your shell without putting it in the image:
- ```bash
- docker run --rm -p 3000:3000 -e NCBI_API_KEY medical-mcp:local
- ```
- stdio still works when a client owns the container's standard input. Keep stdin open and do not allocate a terminal:
- ```bash
- docker run -i --rm medical-mcp:local node build/index.js
- ```
- `-i` keeps stdin open for protocol messages. Leave off `-t`. A TTY is for an interactive terminal and can alter the bytes this protocol uses. Logs stay on stderr so they are not mixed into stdout. The lesson and the Kubernetes steps are in [docs/learning-docker-kubernetes.md](docs/learning-docker-kubernetes.md).
- ## Usage Examples
- ### Search for Drug Information
- ```json
- {
- "tool": "search-drugs",
- "arguments": { "query": "Tylenol", "limit": 5 }
- }
- ```
- ### Search Medical Literature (with Evidence Grading)
- Results now include evidence tags:
- ```
- 1. Efficacy of COVID-19 Treatments: A Meta-Analysis
- Evidence: [Systematic Review / Meta-Analysis β’ tool grade I]
- Authors: Smith J, Jones K...
- 2. Randomized Trial of Remdesivir in Adults
- Evidence: [Randomized Controlled Trial β’ tool grade II]
- Authors: Chen L, Wang M...
- ```
- ### Run Health Check
- ```json
- { "tool": "health-check", "arguments": {} }
- ```
- Returns:
- ```
- β FDA: healthy (234ms)
- β PubMed: healthy (156ms)
- β WHO: healthy (890ms)
- β RxNorm: healthy (312ms)
- β ClinicalTrials: healthy (445ms)
- β SemanticScholar: healthy (189ms)
- NCBI API Key: β Configured (10 req/sec PubMed)
- ```
- ## Architecture
- ### Resilience Stack
- Every API call flows through a three-layer resilience stack:
- ```
- Request β Rate Limiter β Circuit Breaker β Retry (with backoff) β Upstream API
- ```
- - **Rate Limiter** β Per-source token bucket prevents exceeding API limits (PubMed: 3/sec without key, 10/sec with; FDA: 4/sec; Google Scholar: 0.2/sec)
- - **Circuit Breaker** β After 3 consecutive failures, the circuit opens for 60s, preventing cascade failures. Transitions: CLOSED β OPEN β HALF_OPEN β CLOSED
- - **Retry** β Exponential backoff with full jitter on transient failures (429, 5xx, network errors). Max 2 retries
- ### Evidence Grading
- PubMed and multi-database results are automatically classified:
- | Grade | Study Type | Examples |
- | ----- | --------------------------------- | --------------------------------------------- |
- | I | Systematic Review / Meta-Analysis | Cochrane reviews, PRISMA studies |
- | II | Randomized Controlled Trial | Double-blind placebo-controlled trials |
- | III | Cohort / Case-Control Study | Prospective, retrospective, population-based |
- | IV | Case Report / Case Series | Clinical case presentations |
- | V | Expert Opinion / Editorial | Commentaries, perspectives, narrative reviews |
- These tags are automatic labels from the title and abstract, not independently checked grades.
- ### Automatic Fallback
- When `MONID_API_KEY` is set, Scholar/AAP search and PMC HTML fetch go through **Monid TinyFish**. Without a key, Scholar falls back to **Semantic Scholar's API** β free, well-structured, 100 req/sec, no API key needed.
- ### Response Validation
- All upstream API responses are validated against Zod schemas. If a source changes their API response format, the server logs a warning but continues operating with raw data β no crashes, just alerts.
- ## Data Sources
- | Source | Coverage | Update Frequency | Resilience |
- | ----------------------------------- | ---------------------------------------- | ---------------- | ---------------------------------- |
- | **FDA** | US approved drug labels | Real-time | Circuit breaker + retry |
- | **DailyMed** | US structured product labels | Daily | Circuit breaker + retry |
- | **TGA ARTG** | Australian Register of Therapeutic Goods | Real-time | Circuit breaker + retry |
- | **Health Canada DPD** | Canadian marketed/approved drugs | Real-time | Circuit breaker + retry |
- | **EMA** | EU centrally authorised medicines | Twice daily JSON | In-memory cache + retry |
- | **FDA FAERS / recalls / shortages** | US safety signals | Real-time | Circuit breaker + retry |
- | **WHO** | Global health stats (194 countries) | Annual | Circuit breaker + retry |
- | **PubMed** | 30M+ medical citations | Daily | Circuit breaker + retry + NCBI key |
- | **RxNorm** | Standardized drug nomenclature (US) | Weekly | Circuit breaker + retry |
- | **TinyFish via Monid** | Research papers + domain-scoped web | Real-time | Optional `MONID_API_KEY` |
- | **Semantic Scholar** | 200M+ papers with citation data | Real-time | Circuit breaker + retry |
- | **AAP** | Bright Futures & policy statements | Periodic | Graceful degradation |
- | **Pediatric Journals** | Major pediatric journals | Daily | Circuit breaker + retry |
- | **ClinicalTrials.gov** | Interventional and observational trials | Real-time | Circuit breaker + retry |
- ## Configuration
- ### Environment Variables
- **Performance & Reliability:**
- | Variable | Default | Description |
- | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `NCBI_API_KEY` | _(none)_ | Free PubMed API key β 3x throughput. Get one at [NCBI](https://www.ncbi.nlm.nih.gov/account/settings/) |
- | `MONID_API_KEY` | _(none)_ | Optional. When set, Scholar/AAP/PMC HTML use Monid's TinyFish search and fetch (Tavily-style web scraper). Get a key at [Monid](https://app.monid.ai/access/api-keys) |
- | `TINYFISH_API_KEY` | _(none)_ | Optional fallback if you call TinyFish directly instead of through Monid. |
- | `TYPESAFE_API_KEY` | _(none)_ | Optional. Needed to rerank literature hits with JEV (`jev-1.13.0`). Without it, search works as before. Get a key at [TypeSafe](https://typesafe.ai) |
- | `LOG_LEVEL` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARN`, `ERROR`, `SILENT` |
- **Cache:**
- | Variable | Default | Description |
- | -------------------------- | --------- | ----------------------------- |
- | `CACHE_ENABLED` | `true` | Enable/disable caching |
- | `CACHE_MAX_SIZE` | `1000` | Maximum cache entries |
- | `CACHE_TTL_FDA` | `86400` | FDA TTL in seconds (24h) |
- | `CACHE_TTL_PUBMED` | `3600` | PubMed TTL (1h) |
- | `CACHE_TTL_WHO` | `604800` | WHO TTL (7d) |
- | `CACHE_TTL_RXNORM` | `2592000` | RxNorm TTL (30d) |
- | `CACHE_TTL_GOOGLE_SCHOLAR` | `3600` | Google Scholar TTL (1h) |
- | `CACHE_TTL_BRIGHT_FUTURES` | `2592000` | Bright Futures TTL (30d) |
- | `CACHE_TTL_AAP_POLICY` | `604800` | AAP Policy TTL (7d) |
- | `CACHE_TTL_REGULATORS` | `86400` | TGA/EMA/Health Canada TTL |
- | `CACHE_TTL_SAFETY` | `3600` | FAERS/recalls/shortages TTL |
- | `CACHE_TTL_TRIALS` | `3600` | Clinical trial search TTL |
- | `CACHE_CLEANUP_INTERVAL` | `300000` | Cleanup interval in ms (5min) |
- **Deduplication:**
- | Variable | Default | Description |
- | ---------------------------- | ------- | ----------------------------------------- |
- | `DEDUP_ENABLED` | `true` | Enable/disable cross-source deduplication |
- | `DEDUP_SIMILARITY_THRESHOLD` | `0.9` | Fuzzy title match threshold (0.0β1.0) |
- | `DEDUP_LOG_REMOVED` | `false` | Log removed duplicates |
- **Performance**: Cached responses return in <10ms vs 800β1500ms for API calls. Expected hit rate: 60%+ for common queries.
- ## Security & Privacy
- - β **Localhost-only** β Server runs locally, no external access
- - β **No data storage** β All queries are real-time, nothing saved to disk
- - β **Process isolation** β Medical data stays on your machine
- - β **No API keys required** β Works without credentials (NCBI and Monid keys are optional)
- ## Technical Details
- **Built with:** Node.js, TypeScript, MCP SDK
- **Dependencies:** `@modelcontextprotocol/sdk`, `superagent`, `zod`, `express`, `cors`
- **Platforms:** macOS, Windows, Linux
- **Source layout:**
- ```
- src/
- βββ index.ts # MCP tool definitions
- βββ utils.ts # Core API functions + formatters
- βββ constants.ts # API URLs, config constants
- βββ types.ts # TypeScript types
- βββ logger.ts # Structured leveled logging
- βββ rank/ # Optional JEV post-retrieval ranker (question vs abstract)
- β βββ policy.ts # Keep / demote / drop β no HTTP
- β βββ jev-client.ts # TypeSafe System One client (jev-1.13.0)
- βββ cache/
- β βββ config.ts # TTL policies, env var support
- β βββ manager.ts # In-memory LRU cache
- βββ resilience/
- β βββ index.ts # Composed resilientCall()
- β βββ circuit-breaker.ts # Per-source circuit breaker
- β βββ retry.ts # Exponential backoff + jitter
- β βββ rate-limiter.ts # Token bucket rate limiter
- βββ validation/
- β βββ schemas.ts # Zod schemas for API responses
- βββ sources/ # Country/source registry + adapters
- β βββ adapters/ # FDA, TGA, Health Canada, EMA, DailyMed, FAERS, trials, TinyFish
- β βββ ...
- βββ utils/
- βββ deduplication.ts # Cross-source paper dedup
- βββ evidence-grading.ts # Study type classification
- βββ semantic-scholar.ts # Semantic Scholar API client
- ```
- ## Medical Disclaimer
- β οΈ **Important**: This tool provides information from authoritative sources but should **not** replace professional medical advice, diagnosis, or treatment. Always consult qualified healthcare professionals for medical decisions.
- ## Contributing
- β **If this project helps you, please star it on GitHub!** β
- Contributions welcome! Please open an issue or submit a pull request.
- ## License
- MIT License β see [LICENSE.md](LICENSE.md) for details.
- ## Support
- If you find this project useful, consider supporting it:
- **β‘ Lightning Network**
- ```
- lnbc1pjhhsqepp5mjgwnvg0z53shm22hfe9us289lnaqkwv8rn2s0rtekg5vvj56xnqdqqcqzzsxqyz5vqsp5gu6vh9hyp94c7t3tkpqrp2r059t4vrw7ps78a4n0a2u52678c7yq9qyyssq7zcferywka50wcy75skjfrdrk930cuyx24rg55cwfuzxs49rc9c53mpz6zug5y2544pt8y9jflnq0ltlha26ed846jh0y7n4gm8jd3qqaautqa
- ```
- **βΏ Bitcoin**: [bc1ptzvr93pn959xq4et6sqzpfnkk2args22ewv5u2th4ps7hshfaqrshe0xtp](https://mempool.space/address/bc1ptzvr93pn959xq4et6sqzpfnkk2args22ewv5u2th4ps7hshfaqrshe0xtp)
- **Ξ Ethereum/EVM**: [0x42ea529282DDE0AA87B42d9E83316eb23FE62c3f](https://etherscan.io/address/0x42ea529282DDE0AA87B42d9E83316eb23FE62c3f)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itβs helped, pass it on.