Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jamesanz--medical-mcp/badge.svg)](/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

i

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.

  1. # 🩺 Medical MCP Server
  2. > **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.
  3. An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that brings authoritative medical information into AI coding environments like Cursor and Claude Desktop.
  4. <a href="https://glama.ai/mcp/servers/@JamesANZ/medical-mcp">
  5. <img width="380" height="200" src="https://glama.ai/mcp/servers/@JamesANZ/medical-mcp/badge" alt="medical-mcp MCP server" />
  6. </a>
  7. [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/JamesANZ/medical-mcp)](https://archestra.ai/mcp-catalog/jamesanz__medical-mcp)
  8. ## Why Use Medical MCP?
  9. - πŸ”’ **Your Data Never Leaves** – Runs 100% locally; no tracking, no logs, no cloud
  10. - πŸ†“ **No API Keys** – Works out of the box, zero configuration
  11. - πŸ₯ **Authoritative Sources** – FDA, TGA, Health Canada, EMA, DailyMed, WHO, PubMed, RxNorm, ClinicalTrials.gov
  12. - ⚑ **Easy Setup** – One-click install in [Cursor](https://cursor.sh) or simple manual setup
  13. - πŸ”¬ **Comprehensive** – Drug info, health stats, medical literature, clinical guidelines, pediatric sources
  14. - πŸ›‘οΈ **Resilient** – Circuit breakers, retry with backoff, rate limiting, and automatic fallbacks
  15. - πŸ“Š **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.
  16. - πŸ₯ **Health Monitoring** – Built-in health check tool to diagnose source availability
  17. ## What's New in v2.0
  18. - **Resilience Layer** – Circuit breakers per source, retry with exponential backoff + jitter, per-source token bucket rate limiters
  19. - **Monid web search** – Scholar, AAP, and PMC HTML go through Monid TinyFish (Tavily-style search/fetch). Semantic Scholar is the no-key fallback
  20. - **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.
  21. - **Response Validation** – Zod schemas validate all upstream API responses, logging warnings on schema drift without breaking
  22. - **NCBI API Key Support** – Optional `NCBI_API_KEY` env var boosts PubMed from 3 req/sec to 10 req/sec
  23. - **Health Check Tool** – `health-check` pings all upstream sources and reports latency, circuit breaker states, rate limiter status, and cache health
  24. - **Structured Logging** – Leveled, structured logging (DEBUG/INFO/WARN/ERROR) with source tracking and timing for every API call
  25. - **Request Timeouts** – All upstream calls have explicit response/deadline timeouts to prevent hanging
  26. ## Quick Start
  27. **Install in Cursor (Recommended):**
  28. [πŸ”— Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=medical-mcp&config=eyJtZWRpY2FsLW1jcCI6eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1lZGljYWwtbWNwIl19fQ==)
  29. **Or install manually:**
  30. ```bash
  31. npm install -g medical-mcp
  32. # Or from source:
  33. git clone https://github.com/JamesANZ/medical-mcp.git
  34. cd medical-mcp && npm install && npm run build
  35. ```
  36. ## Features
  37. ### πŸ’Š Drug Information
  38. - **`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.
  39. - **`search-drug-nomenclature`** – Standardized drug names via RxNorm (`limit` defaults to 25)
  40. - **`search-drug-safety`** – FDA FAERS adverse events (with report IDs), recalls, and shortages
  41. ### πŸ“Š Health Statistics
  42. - **`get-health-statistics`** – WHO Global Health Observatory data (life expectancy, mortality, disease prevalence)
  43. ### πŸ”¬ Medical Literature
  44. - **`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.
  45. - **`rank-search-hits`** – Same rerank for a list you already have (title + abstract). Retrieval ranking only β€” not diagnosis or advice.
  46. - **`get-article-details`** – Detailed article info by PMID
  47. - **`search-google-scholar`** – Academic papers via Monid TinyFish (`research_paper`) when `MONID_API_KEY` is set; otherwise Semantic Scholar
  48. - **`search-medical-journals`** – Top journals (NEJM, JAMA, Lancet, BMJ, Nature Medicine)
  49. ### πŸ₯ Clinical Tools
  50. - **`search-clinical-guidelines`** – Practice recommendations from medical organizations
  51. - **`search-clinical-trials`** – ClinicalTrials.gov
  52. - **`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.
  53. ### πŸ‘Ά Pediatric Sources
  54. - **`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.
  55. - **`search-pediatric-literature`** – Research from major pediatric journals. Optional `question` / `rerank` like medical literature.
  56. - **`search-pediatric-drugs`** – Drugs with pediatric labeling, NDC, manufacturer, and DailyMed URL
  57. ### πŸ›‘οΈ Reliability & Monitoring
  58. - **`health-check`** – Ping all upstream sources, report latency/status, circuit breaker states, and cache health
  59. - **`get-cache-stats`** – View cache statistics (hit rate, memory usage, entry count)
  60. ## Installation
  61. ### Cursor (One-Click)
  62. Click the install link above or use:
  63. ```
  64. cursor://anysphere.cursor-deeplink/mcp/install?name=medical-mcp&config=eyJtZWRpY2FsLW1jcCI6eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1lZGljYWwtbWNwIl19fQ==
  65. ```
  66. ### Manual Installation
  67. **Requirements:** Node.js 18+ and npm
  68. ```bash
  69. git clone https://github.com/JamesANZ/medical-mcp.git
  70. cd medical-mcp
  71. npm install
  72. npm run build
  73. npm start
  74. ```
  75. ### Claude Desktop
  76. Add to `claude_desktop_config.json`:
  77. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  78. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  79. ```json
  80. {
  81. "mcpServers": {
  82. "medical-mcp": {
  83. "command": "node",
  84. "args": ["/absolute/path/to/medical-mcp/build/index.js"],
  85. "env": {
  86. "NCBI_API_KEY": "your_optional_key_here"
  87. }
  88. }
  89. }
  90. }
  91. ```
  92. Restart Claude Desktop after configuration.
  93. ### Docker
  94. 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.
  95. ```bash
  96. docker build -t medical-mcp:local .
  97. docker run --name medical-mcp --rm -p 3000:3000 medical-mcp:local
  98. ```
  99. 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.
  100. ```bash
  101. docker run --name medical-mcp --rm -p 3010:3000 medical-mcp:local
  102. ```
  103. In another terminal:
  104. ```bash
  105. docker logs medical-mcp
  106. docker stop medical-mcp
  107. ```
  108. `docker stop` sends SIGTERM. The process stops accepting connections and exits.
  109. 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`.
  110. Pass an optional key from your shell without putting it in the image:
  111. ```bash
  112. docker run --rm -p 3000:3000 -e NCBI_API_KEY medical-mcp:local
  113. ```
  114. stdio still works when a client owns the container's standard input. Keep stdin open and do not allocate a terminal:
  115. ```bash
  116. docker run -i --rm medical-mcp:local node build/index.js
  117. ```
  118. `-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).
  119. ## Usage Examples
  120. ### Search for Drug Information
  121. ```json
  122. {
  123. "tool": "search-drugs",
  124. "arguments": { "query": "Tylenol", "limit": 5 }
  125. }
  126. ```
  127. ### Search Medical Literature (with Evidence Grading)
  128. Results now include evidence tags:
  129. ```
  130. 1. Efficacy of COVID-19 Treatments: A Meta-Analysis
  131. Evidence: [Systematic Review / Meta-Analysis β€’ tool grade I]
  132. Authors: Smith J, Jones K...
  133. 2. Randomized Trial of Remdesivir in Adults
  134. Evidence: [Randomized Controlled Trial β€’ tool grade II]
  135. Authors: Chen L, Wang M...
  136. ```
  137. ### Run Health Check
  138. ```json
  139. { "tool": "health-check", "arguments": {} }
  140. ```
  141. Returns:
  142. ```
  143. βœ… FDA: healthy (234ms)
  144. βœ… PubMed: healthy (156ms)
  145. βœ… WHO: healthy (890ms)
  146. βœ… RxNorm: healthy (312ms)
  147. βœ… ClinicalTrials: healthy (445ms)
  148. βœ… SemanticScholar: healthy (189ms)
  149. NCBI API Key: βœ… Configured (10 req/sec PubMed)
  150. ```
  151. ## Architecture
  152. ### Resilience Stack
  153. Every API call flows through a three-layer resilience stack:
  154. ```
  155. Request β†’ Rate Limiter β†’ Circuit Breaker β†’ Retry (with backoff) β†’ Upstream API
  156. ```
  157. - **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)
  158. - **Circuit Breaker** β€” After 3 consecutive failures, the circuit opens for 60s, preventing cascade failures. Transitions: CLOSED β†’ OPEN β†’ HALF_OPEN β†’ CLOSED
  159. - **Retry** β€” Exponential backoff with full jitter on transient failures (429, 5xx, network errors). Max 2 retries
  160. ### Evidence Grading
  161. PubMed and multi-database results are automatically classified:
  162. | Grade | Study Type | Examples |
  163. | ----- | --------------------------------- | --------------------------------------------- |
  164. | I | Systematic Review / Meta-Analysis | Cochrane reviews, PRISMA studies |
  165. | II | Randomized Controlled Trial | Double-blind placebo-controlled trials |
  166. | III | Cohort / Case-Control Study | Prospective, retrospective, population-based |
  167. | IV | Case Report / Case Series | Clinical case presentations |
  168. | V | Expert Opinion / Editorial | Commentaries, perspectives, narrative reviews |
  169. These tags are automatic labels from the title and abstract, not independently checked grades.
  170. ### Automatic Fallback
  171. 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.
  172. ### Response Validation
  173. 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.
  174. ## Data Sources
  175. | Source | Coverage | Update Frequency | Resilience |
  176. | ----------------------------------- | ---------------------------------------- | ---------------- | ---------------------------------- |
  177. | **FDA** | US approved drug labels | Real-time | Circuit breaker + retry |
  178. | **DailyMed** | US structured product labels | Daily | Circuit breaker + retry |
  179. | **TGA ARTG** | Australian Register of Therapeutic Goods | Real-time | Circuit breaker + retry |
  180. | **Health Canada DPD** | Canadian marketed/approved drugs | Real-time | Circuit breaker + retry |
  181. | **EMA** | EU centrally authorised medicines | Twice daily JSON | In-memory cache + retry |
  182. | **FDA FAERS / recalls / shortages** | US safety signals | Real-time | Circuit breaker + retry |
  183. | **WHO** | Global health stats (194 countries) | Annual | Circuit breaker + retry |
  184. | **PubMed** | 30M+ medical citations | Daily | Circuit breaker + retry + NCBI key |
  185. | **RxNorm** | Standardized drug nomenclature (US) | Weekly | Circuit breaker + retry |
  186. | **TinyFish via Monid** | Research papers + domain-scoped web | Real-time | Optional `MONID_API_KEY` |
  187. | **Semantic Scholar** | 200M+ papers with citation data | Real-time | Circuit breaker + retry |
  188. | **AAP** | Bright Futures & policy statements | Periodic | Graceful degradation |
  189. | **Pediatric Journals** | Major pediatric journals | Daily | Circuit breaker + retry |
  190. | **ClinicalTrials.gov** | Interventional and observational trials | Real-time | Circuit breaker + retry |
  191. ## Configuration
  192. ### Environment Variables
  193. **Performance & Reliability:**
  194. | Variable | Default | Description |
  195. | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  196. | `NCBI_API_KEY` | _(none)_ | Free PubMed API key β€” 3x throughput. Get one at [NCBI](https://www.ncbi.nlm.nih.gov/account/settings/) |
  197. | `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) |
  198. | `TINYFISH_API_KEY` | _(none)_ | Optional fallback if you call TinyFish directly instead of through Monid. |
  199. | `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) |
  200. | `LOG_LEVEL` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARN`, `ERROR`, `SILENT` |
  201. **Cache:**
  202. | Variable | Default | Description |
  203. | -------------------------- | --------- | ----------------------------- |
  204. | `CACHE_ENABLED` | `true` | Enable/disable caching |
  205. | `CACHE_MAX_SIZE` | `1000` | Maximum cache entries |
  206. | `CACHE_TTL_FDA` | `86400` | FDA TTL in seconds (24h) |
  207. | `CACHE_TTL_PUBMED` | `3600` | PubMed TTL (1h) |
  208. | `CACHE_TTL_WHO` | `604800` | WHO TTL (7d) |
  209. | `CACHE_TTL_RXNORM` | `2592000` | RxNorm TTL (30d) |
  210. | `CACHE_TTL_GOOGLE_SCHOLAR` | `3600` | Google Scholar TTL (1h) |
  211. | `CACHE_TTL_BRIGHT_FUTURES` | `2592000` | Bright Futures TTL (30d) |
  212. | `CACHE_TTL_AAP_POLICY` | `604800` | AAP Policy TTL (7d) |
  213. | `CACHE_TTL_REGULATORS` | `86400` | TGA/EMA/Health Canada TTL |
  214. | `CACHE_TTL_SAFETY` | `3600` | FAERS/recalls/shortages TTL |
  215. | `CACHE_TTL_TRIALS` | `3600` | Clinical trial search TTL |
  216. | `CACHE_CLEANUP_INTERVAL` | `300000` | Cleanup interval in ms (5min) |
  217. **Deduplication:**
  218. | Variable | Default | Description |
  219. | ---------------------------- | ------- | ----------------------------------------- |
  220. | `DEDUP_ENABLED` | `true` | Enable/disable cross-source deduplication |
  221. | `DEDUP_SIMILARITY_THRESHOLD` | `0.9` | Fuzzy title match threshold (0.0–1.0) |
  222. | `DEDUP_LOG_REMOVED` | `false` | Log removed duplicates |
  223. **Performance**: Cached responses return in <10ms vs 800–1500ms for API calls. Expected hit rate: 60%+ for common queries.
  224. ## Security & Privacy
  225. - βœ… **Localhost-only** – Server runs locally, no external access
  226. - βœ… **No data storage** – All queries are real-time, nothing saved to disk
  227. - βœ… **Process isolation** – Medical data stays on your machine
  228. - βœ… **No API keys required** – Works without credentials (NCBI and Monid keys are optional)
  229. ## Technical Details
  230. **Built with:** Node.js, TypeScript, MCP SDK
  231. **Dependencies:** `@modelcontextprotocol/sdk`, `superagent`, `zod`, `express`, `cors`
  232. **Platforms:** macOS, Windows, Linux
  233. **Source layout:**
  234. ```
  235. src/
  236. β”œβ”€β”€ index.ts # MCP tool definitions
  237. β”œβ”€β”€ utils.ts # Core API functions + formatters
  238. β”œβ”€β”€ constants.ts # API URLs, config constants
  239. β”œβ”€β”€ types.ts # TypeScript types
  240. β”œβ”€β”€ logger.ts # Structured leveled logging
  241. β”œβ”€β”€ rank/ # Optional JEV post-retrieval ranker (question vs abstract)
  242. β”‚ β”œβ”€β”€ policy.ts # Keep / demote / drop β€” no HTTP
  243. β”‚ └── jev-client.ts # TypeSafe System One client (jev-1.13.0)
  244. β”œβ”€β”€ cache/
  245. β”‚ β”œβ”€β”€ config.ts # TTL policies, env var support
  246. β”‚ └── manager.ts # In-memory LRU cache
  247. β”œβ”€β”€ resilience/
  248. β”‚ β”œβ”€β”€ index.ts # Composed resilientCall()
  249. β”‚ β”œβ”€β”€ circuit-breaker.ts # Per-source circuit breaker
  250. β”‚ β”œβ”€β”€ retry.ts # Exponential backoff + jitter
  251. β”‚ └── rate-limiter.ts # Token bucket rate limiter
  252. β”œβ”€β”€ validation/
  253. β”‚ └── schemas.ts # Zod schemas for API responses
  254. β”œβ”€β”€ sources/ # Country/source registry + adapters
  255. β”‚ β”œβ”€β”€ adapters/ # FDA, TGA, Health Canada, EMA, DailyMed, FAERS, trials, TinyFish
  256. β”‚ └── ...
  257. └── utils/
  258. β”œβ”€β”€ deduplication.ts # Cross-source paper dedup
  259. β”œβ”€β”€ evidence-grading.ts # Study type classification
  260. └── semantic-scholar.ts # Semantic Scholar API client
  261. ```
  262. ## Medical Disclaimer
  263. ⚠️ **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.
  264. ## Contributing
  265. ⭐ **If this project helps you, please star it on GitHub!** ⭐
  266. Contributions welcome! Please open an issue or submit a pull request.
  267. ## License
  268. MIT License – see [LICENSE.md](LICENSE.md) for details.
  269. ## Support
  270. If you find this project useful, consider supporting it:
  271. **⚑ Lightning Network**
  272. ```
  273. lnbc1pjhhsqepp5mjgwnvg0z53shm22hfe9us289lnaqkwv8rn2s0rtekg5vvj56xnqdqqcqzzsxqyz5vqsp5gu6vh9hyp94c7t3tkpqrp2r059t4vrw7ps78a4n0a2u52678c7yq9qyyssq7zcferywka50wcy75skjfrdrk930cuyx24rg55cwfuzxs49rc9c53mpz6zug5y2544pt8y9jflnq0ltlha26ed846jh0y7n4gm8jd3qqaautqa
  274. ```
  275. **β‚Ώ Bitcoin**: [bc1ptzvr93pn959xq4et6sqzpfnkk2args22ewv5u2th4ps7hshfaqrshe0xtp](https://mempool.space/address/bc1ptzvr93pn959xq4et6sqzpfnkk2args22ewv5u2th4ps7hshfaqrshe0xtp)
  276. **Ξ Ethereum/EVM**: [0x42ea529282DDE0AA87B42d9E83316eb23FE62c3f](https://etherscan.io/address/0x42ea529282DDE0AA87B42d9E83316eb23FE62c3f)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.