Search medical, clinical, radiological and dental images from your terminal and from Claude Code — powered by Open-i (the U.S. National Library of Medicine's Open Access Biomedical Image Search Engine). No API key, no sign-up, no rate-limit token — Open-i is a fully public research API, and this project is the fastest way to query it from an AI coding agent or a shell.
This repository gives you several ways to reach the same Open-i search engine, all sharing one tested core (openi_client.py):
| # | Component | What it is | How you use it |
|---|---|---|---|
| 1 | Claude Code plugin | A .claude-plugin/plugin.json + self-hosted marketplace, bundling the MCP server and an /openi:medical-image skill. |
/plugin marketplace add + /plugin install — the recommended, one-command way to get the tool + skill in every Claude Code session. |
| 2 | medical-image skill |
A model-invocable Skill (/openi:medical-image <topic>). |
The quick way: one slash command finds + returns (or embeds) the best image. Claude also triggers it on its own while writing notes. |
| 3 | MCP server (server.py) |
A Model Context Protocol server exposing a search_openi_images tool. |
Claude Code (or any MCP client) calls it for you, mid-conversation, and returns images as Markdown links. |
| 4 | openi CLI (cli.py + openi) |
A standalone terminal command. | You type openi "dental anatomy" and get results printed in your console — no chat needed. |
| 5 | Manual .mcp.json / claude mcp add |
The classic, no-plugin way to wire up component #3. | Useful if you don't want to use the plugin/marketplace system, or need per-project config. |
The Open-i API is public and requires no API key.
ℹ️ API reference: always double-check the parameters and codes against the official docs at https://openi.nlm.nih.gov/services. This project targets the
GET /api/searchendpoint documented there.
⚠️ Don't confuse Open-i with NCBI's E-utilities.openi.nlm.nih.gov(this project's only dependency) genuinely needs no key at all — it's a fully open, unauthenticated REST endpoint. A different, related NLM service — the NCBI E-utilities API ateutils.ncbi.nlm.nih.gov/www.ncbi.nlm.nih.gov(used for things like PubMed/PMC full-text lookups) — does require (or strongly recommend) an API key for higher rate limits. This project never calls that API: thearticle_urlfield in each result is just a plain, human-clickable link built from thepmcidOpen-i already returns (e.g.https://www.ncbi.nlm.nih.gov/pmc/articles/PMC123456/), not an authenticated API call. So: no key needed anywhere in this repo, today or if it grows — just be aware the two services are not the same thing if you extend this project to query NCBI directly.
- What can I search for?
- Requirements
- Windows notes
- Quick start (60 seconds)
- 0. Install as a Claude Code plugin (recommended)
- 1. The MCP server
- 2. The
openiterminal command - 3. Install the server into Claude Code (manual, no plugin)
- Using it inside Claude Code (let the agent do it for you)
- Filter codes reference
- The Portuguese → English translation rule
- How it works internally
- Troubleshooting
- Project layout
- License
Open-i indexes figures, charts, X-rays, CT/MRI scans, ultrasound, histology and clinical photographs extracted from PubMed Central articles and other NLM collections. Typical uses:
- A dentistry reference:
openi "dental anatomy" --type g - A clinical photo of a procedure:
openi "oral incision" --type ph - A radiograph:
openi "panoramic radiograph mandible" --type x - A chart/diagram for a paper or slide deck:
openi "bone remodeling diagram" --type g
- Python 3.10 or newer (
python3 --version) - Internet access to
https://openi.nlm.nih.gov(public, no API key/account needed) - The Claude Code CLI — verify with
claude --version - Either of these, depending on which install path you pick:
uv— for the plugin install path (recommended, no venv needed)- pip + the ability to create a virtual environment (
python3 -m venv) — for the manual install path
This project is fully tested on Windows (Git Bash + PowerShell), with two small differences from the Linux/macOS commands used throughout this README:
-
Venv layout:
python -m venv .venvcreates.venv\Scripts\python.exeon Windows, not.venv/bin/python. Theopenilauncher already detects both automatically — you only need to adjust the path yourself when typing aclaude mcp add/.mcp.jsoncommand by hand. -
$(pwd)substitution: this only works in a POSIX-style shell (Git Bash, WSL). In PowerShell/cmd, write the absolute path directly instead:# PowerShell — from inside the cloned repo claude mcp add openi -s user -- "E:\path\to\mcp-openi-server\.venv\Scripts\python.exe" "E:\path\to\mcp-openi-server\server.py"
Everything else (the openi command, cli.py, server.py) behaves identically on Windows once the venv is created — console output is forced to UTF-8 internally, so accented characters and the … ellipsis print correctly even on a legacy cp1252 terminal.
No clone, no venv, no pip install. Just needs uv on your PATH. Run these three lines (in your shell or inside a Claude Code session as /plugin ...):
claude plugin marketplace add LeviReisJs/mcp-openi-server
claude plugin install openi@openi-marketplace
claude mcp list # should show: plugin:openi:openi ... ✓ ConnectedThen, in any Claude Code session, just ask — e.g. /openi:medical-image dental anatomy — or let Claude reach for it on its own. Done.
Use this if you want the openi terminal command, or prefer not to use the plugin system.
# 1. Clone the repository
git clone https://github.com/LeviReisJs/mcp-openi-server.git
cd mcp-openi-server
# 2. Create an isolated Python environment and install the two dependencies
python3 -m venv .venv
source .venv/bin/activate # Windows (PowerShell): .venv\Scripts\Activate.ps1
pip install -r requirements.txt
# 3. Try the standalone CLI right away
python cli.py "dental anatomy" -n 5# 4a. Register the MCP server with Claude Code — macOS / Linux / Git Bash:
claude mcp add openi -s user -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"# 4b. Register the MCP server with Claude Code — Windows PowerShell
# (run from inside the cloned repo; write out the absolute path):
claude mcp add openi -s user -- "$PWD\.venv\Scripts\python.exe" "$PWD\server.py"Verify either path with claude mcp list — you should see openi ... ✓ Connected.
That's it. The rest of this README explains each piece in depth.
This repository is itself a Claude Code plugin (.claude-plugin/plugin.json) and a self-hosted marketplace (.claude-plugin/marketplace.json) for that one plugin. This is the easiest, most portable way to get search_openi_images into Claude Code — no manual venv, no pip install, no absolute paths to configure. It works because the plugin's MCP entry uses uv run with the ${CLAUDE_PLUGIN_ROOT} variable (resolved automatically by Claude Code to wherever the plugin was installed), so uv fetches mcp and httpx into an ephemeral environment on first run — you never touch a venv.
# Add this repo as a marketplace (only needs to be done once)
claude plugin marketplace add LeviReisJs/mcp-openi-server
# Install the "openi" plugin from it
claude plugin install openi@openi-marketplaceYou can run the same two commands from inside an interactive Claude Code session using the slash-command form instead:
/plugin marketplace add LeviReisJs/mcp-openi-server
/plugin install openi@openi-marketplace
claude plugin list # shows: openi@openi-marketplace ... enabled
claude mcp list # shows: plugin:openi:openi ... ConnectedOr, inside a session, run /mcp to see it listed as a connected server, and /context to confirm the plugin is loaded.
uvinstalled and on yourPATH(the plugin's MCP server is launched viauv run, which needsuvitself — everything else,uvinstalls automatically on first launch).- No Python venv, no
pip install -r requirements.txtneeded for this path —uvhandlesmcpandhttpxtransparently, cached after the first run.
claude plugin marketplace update openi-marketplace # pull the latest plugin.json from GitHub
claude plugin update openi # update the installed plugin
claude plugin uninstall openi # remove it
claude plugin marketplace remove openi-marketplace # stop tracking this marketplace entirelyPrefer the manual route (no plugin system, no marketplace)? Skip to section 3 — it still works exactly as before and is fully supported.
server.py uses the official MCP Python SDK (FastMCP) and communicates over stdio — exactly what Claude Code expects. It exposes two tools:
search_openi_images— the main search tool.openi_reference— returns the filter-code cheat sheet (image types, specialties, article types) without leaving the conversation.
cd mcp-openi-server
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt # installs: mcp, httpxYou normally never launch this by hand — Claude Code does. But you can confirm it starts:
python server.pyIt will wait silently for MCP messages on stdin. Press Ctrl+C to stop. (Seeing nothing is correct: stdio servers don't print to the console.)
| Parameter | Type | Default | Meaning |
|---|---|---|---|
query |
string | — (required) | Search terms, in English (the agent translates for you). |
m |
int | 1 |
Start index of the result window. |
n |
int | 10 |
End index of the result window. |
it |
string | none | Image-type filter code(s), e.g. g, ph, x. |
sp |
string | none | Specialty code(s), e.g. d (dentistry). |
at |
string | none | Article-type code(s). |
Returns a clean object:
On failure it returns { "error": "...", "status": 400, "query": "..." }. HTTP 400 (bad request) and 500 (server error) from the API are caught and reported clearly, as are timeouts and network problems.
The quick shortcut. Run a search and get formatted results straight in your console — no Claude session required.
openi "dental anatomy"Pick one of these:
Option A — symlink onto your PATH (recommended):
# from inside the repo
chmod +x openi
ln -s "$(pwd)/openi" ~/.local/bin/openi # make sure ~/.local/bin is on your PATH
openi "panoramic radiograph"The openi launcher automatically finds and uses the project's .venv, so it works from any directory.
Option B — install as a console script:
source .venv/bin/activate
pip install . # reads pyproject.toml, installs an `openi` command
openi "dental caries"Option C — just call it directly (no install):
python cli.py "dental caries"openi [-h] [-m START] [-n END] [-t TYPE] [-s SPECIALTY] [-a ARTICLE_TYPE]
[--json] [--markdown] [--timeout SECONDS] query [query ...]
| Flag | Meaning |
|---|---|
-m, --start |
Start index (default 1). |
-n, --end |
End index (default 10). |
-t, --type |
Image type, e.g. g graphics, ph photo, x x-ray. |
-s, --specialty |
Specialty code, e.g. d dentistry. |
-a, --article-type |
Article-type code. |
--json |
Print raw JSON (great for piping into jq). |
--markdown |
Print Markdown with inline  image links. |
--timeout |
HTTP timeout in seconds (default 30). |
openi "oral incision" --type ph -n 5 # 5 clinical photos
openi "bone remodeling" --type g --markdown # diagrams, as Markdown
openi "mandible fracture" --json | jq '.results[].image_url'Language note: the CLI sends your text to Open-i as-is (there is no LLM in the loop here). Open-i is English-only, so type English terms —
openi "dental caries", notopeni "cárie". Inside Claude Code, the agent translates automatically (see below).
If you already installed via section 0, you can skip this — it's the same end result via a different mechanism.
This is the manual way to make search_openi_images available in every Claude Code session, without using the plugin/marketplace system.
From inside the cloned repo (so $(pwd) resolves correctly):
claude mcp add openi -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"openiis the name the server will have inside Claude Code.- Everything after
--is the command Claude Code runs to start the server. - Using the
.venvPython guarantees themcpandhttpxdependencies are found.
Add -s user to make it available in all your projects (not just the current directory):
claude mcp add openi -s user -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"claude mcp list # should show: openiOr, inside an interactive Claude Code session, run the slash command /mcp to see connected servers and their tools.
If you use uv:
claude mcp add openi -- uv run --directory "$(pwd)" --with mcp --with httpx python server.pyCopy the provided template and edit the absolute paths:
cp .mcp.json.example .mcp.json{
"mcpServers": {
"openi": {
"command": "/ABSOLUTE/PATH/mcp-openi-server/.venv/bin/python",
"args": ["/ABSOLUTE/PATH/mcp-openi-server/server.py"]
}
}
}Anyone who opens the project in Claude Code will be prompted to enable the openi server automatically.
Add the same block to claude_desktop_config.json
(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json,
Windows: %APPDATA%\Claude\claude_desktop_config.json) and restart the app.
claude mcp remove openiWhen you install this as a plugin, it ships a Skill called medical-image. That gives you a fast, explicit way to trigger an image search without describing the whole workflow every time:
/openi:medical-image radiografia panorâmica de fratura de mandíbula
Claude runs the skill, which tells it to: translate the term to English, pick the right image-type filter, call search_openi_images, choose the most relevant result, and hand it back as a ready-to-paste Markdown image with a [Fonte] link. The skill also knows how to place the image directly into a note when you're working in a notes vault (e.g. Obsidian) — right under the relevant heading, with the citation kept — and can download it for offline use if your vault syncs to a phone/tablet.
Because it's model-invocable, Claude will also reach for the skill on its own when you're writing study notes and a figure would help — you don't have to type the slash command.
You never have to call any command — just ask, and Claude Code decides to use the tool and hands you back an image. Try prompts like:
"Search Open-i for a diagram of dental anatomy and show me the best image."
"Preciso de uma foto clínica de uma incisão oral para uma apresentação — busca no Open-i e me manda o link em Markdown." (Portuguese is fine — the agent translates the query to English before searching.)
"Find an X-ray of a mandible fracture on Open-i and embed it here."
Because the tool's description tells the agent to render results as Markdown image links, Claude will reply with something you can paste anywhere:

*Figure 1. Cross-section showing enamel, dentin and pulp.* — [Source](https://openi.nlm.nih.gov/pmc/articles/PMC123456/)You can also nudge the agent to filter: "only clinical photos" → it sets it="ph"; "only charts/diagrams" → it="g"; "dentistry specialty" → sp="d".
Values below come from the official OAS 2.0 spec at https://openi.nlm.nih.gov/services. Inside Claude Code you can also call the openi_reference tool to print them.
[xg, xm, x, u, ph, p, mc, m, g, c]
| Code | Meaning (common ones) |
|---|---|
g |
graphics — charts, diagrams, illustrations |
ph |
photograph — clinical / gross photo |
x |
X-ray |
xm |
mammography |
xg |
X-ray angiography |
u |
ultrasound |
c |
CT scan |
m |
MRI |
mc |
microscopy / histology |
p |
PET |
[b, bc, c, ca, cc, d, de, dt, e, en, f, eh, g, ge, gr, gy, h, i, id, im, n, ne, nu, o, or, ot, p, py, pu, r, s, t, u, v, vil]
(e.g. d is the dentistry-related specialty; consult the site for the full legend.)
[ab, bk, bf, cr, dp, di, ed, ib, in, lt, mr, ma, ne, ob, pr, or, re, ra, rw, sr, rr, os, hs, ot]
coll (collections: pmc, cxr, usc, hmd, mpx), favor (rank by), fields (search in), plus lic, sub, vid, hmp — see the official docs.
Open-i's index is English-only. This project handles that in two different ways depending on the entry point:
- MCP server (Claude Code): the
search_openi_imagesdocstring explicitly instructs the LLM agent to translate any Portuguese term to English before fillingquery. So"odontolegista"becomesforensic dentistry,"cárie"becomesdental caries, etc. — automatically. openiCLI: there is no LLM, so you should type English terms.
Common translations the agent uses:
| Portuguese | English (sent to Open-i) |
|---|---|
| incisão oral | oral incision |
| odontolegista | forensic dentistry |
| anatomia dental | dental anatomy |
| radiografia panorâmica | panoramic radiograph |
| cárie | dental caries |
┌────────────────────┐
Claude Code ──stdio──▶ server.py │ (MCP tool: search_openi_images)
└─────────┬──────────┘
│ imports
Your terminal ─────────▶ cli.py (openi) │
│ imports
▼
┌────────────────────┐ HTTPS GET
│ openi_client.py ├────────────▶ openi.nlm.nih.gov/api/search
│ • build params │◀──────────── JSON (200 / 400 / 500)
│ • call API (httpx) │
│ • parse + clean │
└────────────────────┘
openi_client.py is the single source of truth: it builds the query parameters, calls the API with httpx, handles HTTP 400/500 and network/timeout errors, strips HTML out of captions, turns relative image paths into absolute URLs, and returns a tidy list of {title, image_url, thumbnail_url, summary, article_url}. Both server.py and cli.py just call it.
| Symptom | Fix |
|---|---|
claude plugin install fails / plugin not found |
Run claude plugin marketplace update openi-marketplace first, then retry install. Confirm with claude plugin marketplace list. |
Plugin installed but claude mcp list shows no plugin:openi:openi |
Make sure uv is installed and on PATH (uv --version) — the plugin's MCP entry runs the server via uv run. |
claude mcp list doesn't show openi (manual/non-plugin install) |
Re-run the claude mcp add command from inside the repo so $(pwd) resolves; check claude mcp get openi. |
| Tool errors with "Could not reach Open-i" | Check your internet/proxy; confirm https://openi.nlm.nih.gov is reachable (curl -I https://openi.nlm.nih.gov). |
ModuleNotFoundError: No module named 'mcp' |
You're not using the venv Python. Point Claude Code at .venv/bin/python (see section 3). |
| No results | Ensure the query is English, broaden the terms, and drop --type/--specialty filters. |
| HTTP 400 | A filter code is invalid — check the reference table. |
openi: command not found |
Finish section 2 (symlink onto PATH or pip install .). |
mcp-openi-server/
├── .claude-plugin/
│ ├── plugin.json # Plugin manifest — makes this repo installable via `claude plugin install`
│ └── marketplace.json # Self-hosted marketplace listing the "openi" plugin (source: "./")
├── skills/
│ └── medical-image/
│ └── SKILL.md # The `/openi:medical-image` skill (quick find + embed)
├── server.py # MCP server (FastMCP, stdio) — the search "engine" for Claude Code
├── cli.py # Standalone CLI implementation
├── openi # Bash launcher so you can run `openi "…"` from anywhere
├── openi_client.py # Shared core: API call + response parsing (used by both)
├── requirements.txt # Runtime deps: mcp, httpx
├── pyproject.toml # Packaging + `openi` console-script entry point
├── .mcp.json.example # Template to auto-load the server per project in Claude Code (manual path)
├── LICENSE # MIT
└── README.md # This file
MIT. Open-i content itself is subject to the terms of the U.S. National Library of Medicine — see https://openi.nlm.nih.gov.
{ "query": "dental anatomy", "total": 42, "returned": 5, "api_url": "https://openi.nlm.nih.gov/api/search?query=dental+anatomy&m=1&n=5", "results": [ { "title": "Dental anatomy of the mandibular molar", "image_url": "https://openi.nlm.nih.gov/imgs/512/1/PMC123/fig1.png", "thumbnail_url": "https://openi.nlm.nih.gov/imgs/150/1/PMC123/fig1.png", "summary": "Figure 1. Cross-section showing enamel, dentin and pulp.", "article_url": "https://openi.nlm.nih.gov/pmc/articles/PMC123456/", "uid": "PMC123-fig1" } ] }