mcp-openi-server — Open-i Medical Image Search for Claude Code (MCP Server + CLI + 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):

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

Related MCP server: PubMed MCP Server

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

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

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]

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:

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

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.