Openi

License: MIT Python 3.10+ MCP Claude Code Plugin

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/search endpoint 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 at eutils.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: the article_url field in each result is just a plain, human-clickable link built from the pmcid Open-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.

---

Table of contents

• 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 openi terminal 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

---

What can I search for?

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

---

Requirements

• 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

---

Windows notes

This project is fully tested on Windows (Git Bash + PowerShell), with two small differences from the Linux/macOS commands used throughout this README:

1. Venv layout: python -m venv .venv creates .venv\Scripts\python.exe on Windows, not .venv/bin/python. The openi launcher already detects both automatically — you only need to adjust the path yourself when typing a claude mcp add/.mcp.json command by hand.

2. $(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.

---

Quick start (60 seconds)

Fastest path — install as a plugin

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 ... ✓ Connected

Then, in any Claude Code session, just ask — e.g. /openi:medical-image dental anatomy — or let Claude reach for it on its own. Done.

Or — standalone CLI / manual install

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.

---

0. Install as a Claude Code plugin (recommended)

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.

Install (one-time)

# 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-marketplace

You 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

Verify

claude plugin list        # shows: openi@openi-marketplace ... enabled
claude mcp list            # shows: plugin:openi:openi ... Connected

Or, inside a session, run /mcp to see it listed as a connected server, and /context to confirm the plugin is loaded.

Requirements for the plugin path specifically

• uv installed and on your PATH (the plugin's MCP server is launched via uv run, which needs uv itself — everything else, uv installs automatically on first launch).
• No Python venv, no pip install -r requirements.txt needed for this path — uv handles mcp and httpx transparently, cached after the first run.

Updating / removing

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 entirely

Prefer the manual route (no plugin system, no marketplace)? Skip to section 3 — it still works exactly as before and is fully supported.

---

1. The MCP server

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.

Install

cd mcp-openi-server
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt    # installs: mcp, httpx

Run it standalone (optional smoke test)

You normally never launch this by hand — Claude Code does. But you can confirm it starts:

python server.py

It 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.)

The search_openi_images tool

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:

{
  "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"
    }
  ]
}

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.

---

2. The openi terminal command

The quick shortcut. Run a search and get formatted results straight in your console — no Claude session required.

openi "dental anatomy"

Make openi available everywhere

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"

CLI options

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).

Examples

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", not openi "cárie". Inside Claude Code, the agent translates automatically (see below).

---

3. Install the server into Claude Code (manual, no plugin)

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.

The exact command

From inside the cloned repo (so $(pwd) resolves correctly):

claude mcp add openi -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

• openi is the name the server will have inside Claude Code.
• Everything after -- is the command Claude Code runs to start the server.
• Using the .venv Python guarantees the mcp and httpx dependencies 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"

Verify

claude mcp list                 # should show: openi

Or, inside an interactive Claude Code session, run the slash command /mcp to see connected servers and their tools.

Alternative A — uv (no manual venv)

If you use uv:

claude mcp add openi -- uv run --directory "$(pwd)" --with mcp --with httpx python server.py

Alternative B — commit a .mcp.json (share with your team)

Copy 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.

Alternative C — Claude Desktop

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.

Removing it

claude mcp remove openi

---

Using it inside Claude Code (let the agent do it for you)

The quick way: the /openi:medical-image skill

When 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.

Or just ask in natural language

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:

![Dental anatomy of the mandibular molar](https://openi.nlm.nih.gov/imgs/512/1/PMC123/fig1.png)
*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".

---

Filter codes reference

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.

Image type (it / --type)

[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

Specialties (sp / --specialty)

[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.)

Article types (at / --article-type)

[ab, bk, bf, cr, dp, di, ed, ib, in, lt, mr, ma, ne, ob, pr, or, re, ra, rw, sr, rr, os, hs, ot]

Other endpoint parameters (advanced, supported by openi_client.py)

coll (collections: pmc, cxr, usc, hmd, mpx), favor (rank by), fields (search in), plus lic, sub, vid, hmp — see the official docs.

---

The Portuguese → English translation rule

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_images docstring explicitly instructs the LLM agent to translate any Portuguese term to English before filling query. So "odontolegista" becomes forensic dentistry, "cárie" becomes dental caries, etc. — automatically.
• openi CLI: 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

---

How it works internally

                         ┌────────────────────┐
   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.

---

Troubleshooting

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 .).

---

Project layout

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

---

License

MIT. Open-i content itself is subject to the terms of the U.S. National Library of Medicine — see https://openi.nlm.nih.gov.