Skip to main content
Glama

Img-License MCP

CI Python License: MIT

An MCP server (FastMCP, stdio) that lets an AI agent illustrate blog articles with images whose licence has been verified at the source: it searches with a licence filter, converts to WebP at the right size, builds the attribution line when the licence requires one, and uploads the file to WordPress with its provenance metadata.

Tool

Source

Returns

search_images

Commons (extmetadata) · Openverse · 4 keyed sources

Candidates with a readable licence, author, dimensions and discard counters

inspect_image

Commons

Re-reads the licence of one image, in any of its URL shapes

prepare_image

Pillow

Downloads, downscales (never upscales) and converts to WebP, with the real byte saving

build_attribution

—

The Photo: Author, LICENCE, via Source paragraph with its three links

upload_to_wordpress

WordPress REST

Uploads the file, writes alt_text and the provenance, and can set the featured image

The golden rule: a candidate whose licence cannot be read from the field its source publishes does not appear in the response, not even with a warning. It is dropped silently and counted in discarded_unknown_license. A licence is never inferred from the domain, the search engine or the thumbnail.


Installation

Requires Python 3.11+ (developed on 3.12).

git clone https://github.com/John-OF/img-license-mcp.git
cd img-license-mcp
python -m venv .venv

Install the dependencies with the virtual environment's Python:

# Windows
.venv\Scripts\python.exe -m pip install -r requirements.txt
# macOS / Linux
.venv/bin/python -m pip install -r requirements.txt

Copy .env.example to .env. No key is needed to get started: Commons and Openverse work as they are. The other sources switch on by themselves when their variable is set.

Variable

Used for

Where to get it

IMG_LICENSE_USER_AGENT

HTTP identity. Without a descriptive UA, Wikimedia answers 403

— (there is a default; set your own)

UNSPLASH_ACCESS_KEY

Unsplash source

https://unsplash.com/oauth/applications

PEXELS_API_KEY

Pexels source

https://www.pexels.com/api/new/

PIXABAY_API_KEY

Pixabay source

https://pixabay.com/api/docs/

NPS_API_KEY

National Park Service source

https://www.nps.gov/subjects/developer/get-started.htm

WP_BASE_URL, WP_USER, WP_APP_PASSWORD

upload_to_wordpress

Users → Profile → Application Passwords

Paste the Application Password with its spaces, exactly as WordPress shows it.

Check that it starts (it waits on stdio; press Ctrl+C to exit):

.venv/bin/python server.py          # Windows: .venv\Scripts\python.exe server.py

Related MCP server: wikipedia-mcp-image-crawler

Registering the server in your MCP client

Always point to the virtual environment's Python, not the system one. In the examples below, replace <path-to-repo> with the absolute path where you cloned the repository (on macOS/Linux, use .venv/bin/python instead of .venv/Scripts/python.exe).

Claude Code, user scope (available in every project):

claude mcp add img-license --scope user -- "<path-to-repo>/.venv/Scripts/python.exe" "<path-to-repo>/server.py"

Claude Code, project scope: copy .mcp.json.example to .mcp.json and fill in the paths. It is loaded automatically when Claude Code opens the folder.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "img-license": {
      "command": "<path-to-repo>/.venv/Scripts/python.exe",
      "args": ["<path-to-repo>/server.py"]
    }
  }
}

Code layout

File

Contents

server.py

FastMCP and the five tools

licensing.py

Licence engine: source code → canonical licence

sources.py

One adapter per source, plus the registry of which key each one needs

imaging.py

Downloads, Commons thumbnails and Pillow helpers

wordpress.py

Credentials and the provenance block

common.py

User-Agent, endpoints and text helpers


Tools

1. search_images(query, license_filter, min_width, sources, limit)

Searches every available source and returns only what has a readable licence.

Parameter

Type

Default

Description

query

str

—

What the photo should show. English works best: most source metadata is in English

license_filter

commercial | no_attribution | any

commercial

See below

min_width

int (0-10000)

1600

Minimum width of the original. prepare_image never upscales, so this is what caps the publishable size

sources

list

all

commons, openverse, unsplash, pexels, pixabay, nps

limit

int (1-50)

12

Candidates returned, already filtered and de-duplicated

The three licence filters:

Value

Lets through

When to use it

commercial

Public domain, CC0, CC BY, CC BY-SA

The default. Commercial use and the right to modify, which resizing and cropping require

no_attribution

Public domain, CC0, stock licences

When you don't want to maintain credit lines. Far fewer results

any

Everything determinable, NC and ND included

Maximum coverage; each result carries its flags so you can decide

Real output (query="Arashiyama bamboo forest", sources=["commons", "openverse"], limit=5), trimmed to one result:

{
  "ok": true,
  "query": "Arashiyama bamboo forest",
  "license_filter": "commercial",
  "min_width": 1600,
  "sources_used": ["commons", "openverse"],
  "candidates_examined": 30,
  "discarded_unknown_license": 0,
  "discarded_not_image": 0,
  "discarded_by_license": 0,
  "discarded_too_small": 4,
  "discarded_unknown_size": 0,
  "duplicates_merged": 0,
  "count": 5,
  "results": [
    {
      "source": "commons",
      "title": "Bamboo Forest, Arashiyama, Kyoto, Japan.jpg",
      "source_page_url": "https://commons.wikimedia.org/wiki/File:Bamboo_Forest,_Arashiyama,_Kyoto,_Japan.jpg",
      "file_url": "https://upload.wikimedia.org/wikipedia/commons/...",
      "license": "CC BY-SA 4.0",
      "license_code": "cc-by-sa-4.0",
      "license_url": "https://creativecommons.org/licenses/by-sa/4.0",
      "attribution_required": true,
      "allows_commercial": true,
      "allows_modification": true,
      "author": "Basile Morin",
      "width": 6558, "height": 4372, "bytes": 17157793
    }
  ],
  "sources_skipped": {
    "unsplash": "UNSPLASH_ACCESS_KEY is not set",
    "pexels": "PEXELS_API_KEY is not set",
    "pixabay": "PIXABAY_API_KEY is not set",
    "nps": "NPS_API_KEY is not set"
  }
}

width/height are always what can be DOWNLOADED, not what the source claims. Several APIs advertise the original's dimensions even when their public URL serves something smaller; if min_width trusted that figure, it would let through photos that then fall short. The original's real size goes separately in original_width/original_height, and that is the one cited in the provenance block on upload.

Source

width/height

original_*

Commons, Openverse, Pexels

The original: its URL serves it whole

Same

Unsplash

Capped at 2400 wide, which is what the URL requests

The full original

Pixabay

Capped at 1280 on the longest side (see limits)

The original, which cannot be downloaded

NPS

Measured by reading the file header

Same

The discard counters say why each candidate fell out, and are worth reading:

Counter

Meaning

discarded_unknown_license

Its licence code could not be read or is not citable (GFDL, Free Art License, attribution…). These are never shown

discarded_not_image

TIFF and friends: Commons' filetype:bitmap lets them through and they are no use on the web. Counted separately so they don't inflate the counter above

discarded_by_license

Readable licence outside the filter (an NC licence with license_filter="commercial")

discarded_too_small / discarded_unknown_size

Below min_width, or no published width

duplicates_merged

Openverse re-indexes Commons: the same file arrives both ways and is merged

The counters cover the candidates processed until limit is reached. In the run above, Openverse returned 15 Flickr photos, all at most 1024 px wide; the four that were processed before the list filled up landed in discarded_too_small. In a real query for "Berlin 2005" (50 Commons candidates), 30 came out as discarded_not_image: all orthophoto TIFFs.

2. inspect_image(url)

Re-reads the licence of one image, to confirm something that reached you some other way. It accepts every Commons URL shape:

URL

resolved_by

commons.wikimedia.org/wiki/File:X.jpg

Commons file page

commons.wikimedia.org/w/index.php?curid=97189369

Commons curid

upload.wikimedia.org/wikipedia/commons/7/7a/X.jpg

direct upload.wikimedia.org file URL

.../thumb/7/7a/X.jpg/1920px-X.jpg

upload.wikimedia.org thumbnail URL

{
  "ok": true,
  "resolved_by": "upload.wikimedia.org thumbnail URL",
  "license": "CC BY-SA 3.0",
  "attribution_required": true,
  "author": "Norbert Nagel",
  "author_url": "https://commons.wikimedia.org/wiki/User:NorbertNagel",
  "width": 4257, "height": 2553
}

Any other host returns ok: false. A licence is never invented from the domain:

{
  "ok": false,
  "host": "www.shutterstock.com",
  "error": "The licence cannot be determined for this host (unsupported host)."
}

3. prepare_image(url, max_width, format, quality)

Download → downscale (never upscale) → convert.

Parameter

Type

Default

url

str

—

max_width

int (64-5000)

1600

format

webp | png | jpeg

webp

quality

int (1-100)

82

Real output for a 6558x4372, 17.2 MB photo on Commons:

download     : https://upload.wikimedia.org/.../1920px-Bamboo_Forest...jpg
reason       : Commons thumbnail from the next bucket up
source       : 1920x1280  (1,010,870 bytes)
output       : 1600x1067  (541,320 bytes)   resized=True
saving_pct   : 46.5 %
format_saving: 5.7 %   (same pixels as JPEG q82)
file         : <temp>/img-license/File-Bamboo_Forest-_Arashiyama-_Kyoto-_Japan-1600px.webp

Note that the 17 MB original is not downloaded, only 1 MB: for Wikimedia URLs the thumbnail is requested from the API. Another real example, a Santorini photo: 531,184 → 242,320 bytes, a 54.4 % saving.

The two savings measure different things:

  • saving_pct — what it weighed against what it weighs, resize and format together. This is the number that matters, and below 30 % it raises an explicit warning.

  • format_saving_pct — the same final pixels re-encoded as JPEG, to isolate the format gain. It is a much harsher yardstick than comparing against the source JPEG, because a freshly encoded JPEG with optimize+progressive compresses very well: on ordinary photos it lands between 5 % and 20 %. It is informative and never triggers a warning on its own.

Warnings it can return, all seen in real tests:

The source is 3840px wide, narrower than the requested 4000px. It is not upscaled: it keeps its real size.
Reconverting barely pays off: it only saves 17.4% (3,919,476 -> 3,238,724 bytes, threshold 30%).
PNG for a photo produces huge files. Use WebP unless you need transparency or crisp text.
The output is LARGER than the source (273.2% more): 1,010,870 -> 3,772,141 bytes. Do not upload this file.

The last one is the PNG case: the same photo went from 1.0 MB to 3.8 MB as PNG.

4. build_attribution(author, license_name, license_url, file_page_url, source, author_url)

{
  "ok": true,
  "html": "<p>Photo: <a href=\"https://commons.wikimedia.org/wiki/User:Basile_Morin\">Basile Morin</a>, <a href=\"https://creativecommons.org/licenses/by-sa/4.0\" rel=\"license\">CC BY-SA 4.0</a>, via <a href=\"https://commons.wikimedia.org/wiki/File:Bamboo_Forest...jpg\">Wikimedia Commons</a></p>",
  "text": "Photo: Basile Morin, CC BY-SA 4.0, via Wikimedia Commons",
  "attribution_required": true,
  "notes": []
}

If the licence does not require credit, the paragraph is still built but flagged, so you can decide:

attribution_required: false
note: CC0 1.0 does not require attribution. The credit is a courtesy, not an obligation: you can leave it out.

The author name is HTML-escaped, so an author with < or & in the name does not break the page.

5. upload_to_wordpress(...)

Parameter

Required

Description

file_path

yes

The output of prepare_image. Never the untouched original

title

yes

Media library title

alt_text

yes

In the site's language. You write it: nothing here invents it

source_url, author, license_name

yes

Go into the provenance block

original_width, original_height

yes

Resolution of the original, before resizing

caption

no

The credit paragraph goes here when the licence requires it

notes

no

Free text prepended to the provenance

attach_to_post

no

Post ID

set_featured

no

Sets the featured image. Requires attach_to_post

It makes two requests by design: the multipart one uploads the binary and a second POST writes the metadata, because WordPress ignores alt_text and description in the multipart body.

The description is built here, not received as free text, so "always" can be verified:

Source: https://commons.wikimedia.org/wiki/File:Bamboo_Forest...jpg
Author: Basile Morin
Licence: CC BY-SA 4.0
Original resolution: 6558x4372
Downloaded: 2026-09-06

The download date comes from the file's mtime, that is, from when prepare_image wrote it.

Real output of an upload to a live WordPress site (domain replaced):

{
  "ok": true,
  "media_id": 608,
  "media_url": "https://example.com/wp-content/uploads/2026/09/File-Bamboo_Forest-_Arashiyama-_Kyoto-_Japan-1600px.webp",
  "edit_url": "https://example.com/wp-admin/post.php?post=608&action=edit",
  "mime": "image/webp",
  "sizes": {
    "thumbnail": "150x150", "medium": "300x200", "medium_large": "768x512",
    "large": "1024x683", "full": "1600x1067"
  },
  "warnings": []
}

Read back afterwards through the unauthenticated API: correct alt_text, the three credit links intact in the caption (with their rel="license"), the full provenance block, and the file served at 541,320 bytes.

Don't panic when checking over REST: description.rendered shows Original resolution: 6558×4372, with a multiplication sign. That is WordPress's wptexturize, which turns an x between numbers into × when rendering. The stored value keeps the x that was sent. WordPress also prepends a <p class="attachment"> with the thumbnail to the rendered description; your text comes after it.


Suggested workflow

  1. search_images("santorini blue domes at sunset") → pick a candidate.

  2. inspect_image(source_page_url) if it came from elsewhere and you want to re-confirm.

  3. prepare_image(file_url) → check saving_pct and the warnings.

  4. build_attribution(...) if attribution_required is true.

  5. upload_to_wordpress(output_path, ..., caption=<the html from step 4>).

Write the alt_text yourself, looking at the photo.


Limits and caveats

Verified against the real services, with dates. None of this is guesswork:

  • Wikimedia answers 403 to generic User-Agents (2026-09-01, 09-02 and reconfirmed 09-06): httpx's default → 403, python-requests/2.32 → 403, a descriptive UA → 200. The default UA points to this repository; if you deploy the server, set IMG_LICENSE_USER_AGENT to your own descriptive UA with a contact.

  • Commons only serves the widths in its bucket list. Building /thumb/.../1600px-X.jpg gives 400; 1280 and 1920 give 200. That is why no thumbnail URL is ever built by hand here: it is requested from the API with iiurlwidth, which rounds up to the next valid bucket.

  • The Commons API misreports thumbwidth (2026-09-06): with iiurlwidth=1600 it answers thumbwidth: 1600x960, but the thumburl it hands over is the 1920px- one and what you download measures 1920x1151. So dimensions are always measured with Pillow on the downloaded bytes, never taken from the declared ones.

  • Anonymous Openverse: page_size max 20 (2026-09-06). With 21 it returns 401 "page_size may not exceed 20 for anonymous requests". The adapter pages in steps of 20 (up to 3 pages) instead of asking for big pages.

  • WebP q82 is the default after the 2026-09-06 measurements (192 KB → 140 KB, 47 KB → 26 KB). Mind that the ~40 % is against the source JPEG. Against a freshly encoded JPEG q82 the advantage is much smaller, and that is what format_saving_pct reports.

  • WebP does not win on high-detail textures without repeatable structure: a crowd photo shrank 19 % and a satellite image of a hurricane 7 %, against 54-86 % for the rest. Hence the 30 % threshold.

  • A photo saved as PNG produces monstrous derivatives: one 1536x850 derivative weighed 2.7 MB, twice its own original.

  • Pixabay with a standard account tops out at 1280 px (2026-09-07). Its API declares imageWidth: 6000, but fullHDURL (1920) and imageURL (original) are not returned unless Pixabay approves full access; the only downloadable field is largeImageURL, scaled to 1280 on its longest side. In practice, with the default min_width of 1600, Pixabay contributes nothing (all of it lands in discarded_too_small). To use it, request full access or search with min_width=1280.

  • The NPS API publishes no dimensions. Without them every photo fell into discarded_unknown_size and the source was invisible. The adapter measures them by downloading only the file header (a few KB, with Pillow's incremental parser), and only for the candidates it is about to return. Real measurements: 1800x1012, 2100x1112, 1800x1192. Only photos credited to the NPS are accepted: a third-party photo on their site is not public domain.

  • Unsplash's fit=max caps the WIDTH, not the longest side. Mixing them up swaps the figures on portrait photos: a 3024x4032 original served with w=2400 is 2400x3200, not 1800x2400.

  • WordPress has no media trash by default (MEDIA_TRASH is off): a REST DELETE without force fails, and with ?force=true it deletes permanently. That is why this server exposes no delete tool. If one is ever added, it should require explicit confirmation.

  • Yoast SEO's og:image does not refresh on the first try when featured_media changes over REST. Seen on a published post on 2026-09-06 and reproduced on 2026-09-07 on a draft, switching the featured image from A to B:

    featured_media

    og:image

    JSON-LD

    after the first POST

    B

    A ← keeps the old one

    B

    after repeating the same POST

    B

    B

    B

    It is not a cache, it is Yoast's indexables table: the JSON-LD updates at once and the og:image does not. That is why set_featured repeats the same POST on purpose; on a site without Yoast the second request is harmless. Even so, check the og:image of the published post.

Known limitations of this version:

  • All six sources were tested against their real APIs (2026-09-07). Pixabay works but contributes nothing with the default min_width, because of the 1280 px ceiling explained above.

  • upload_to_wordpress was tested end to end against a live WordPress site (2026-09-07): a plain media upload, and an upload with attach_to_post + set_featured on a draft, checking afterwards through the API that featured_media, Yoast's og:image and the JSON-LD all pointed at the right image.

  • inspect_image only verifies Wikimedia. Other sources would need their API key and a single-item lookup adapter.

  • Unsplash's guidelines ask you to ping its download endpoint when a photo is used. The download_location field is exposed in the results, but the server does not call it yet.

  • Openverse sometimes returns width/height as null. With a non-zero min_width those candidates fall into discarded_unknown_size.


Development

python -m pip install -r requirements-dev.txt
python -m pytest        # offline: every network call is mocked
python -m ruff check .
python tools/make_demo.py   # regenerates assets/demo.svg

The tests never reach the network: HTTP goes through httpx.MockTransport, any unmocked request fails the test, and the environment is cleared so a local .env cannot leak keys into the suite. It runs in about two seconds. CI runs lint and tests on Python 3.11, 3.12 and 3.13.


Disclaimer

This project is not affiliated with Wikimedia, Openverse, Unsplash, Pexels, Pixabay, the National Park Service or WordPress. It reads the licence each source publishes and refuses to guess, but it is not legal advice: you remain responsible for how you use each image. Respect each API's terms of use and rate limits.

License

MIT © 2026 John Orellana

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      License-first federated image search for AI agents and humans. Exposes MCP tools for concise, attribution-aware image discovery, license probing, and guarded downloads across open, platform, and editorial sources.
      7
      3
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      Enables searching and retrieving images from Wikipedia Commons with detailed metadata including licenses and authors.
      2
      11
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to source real, license-labelled photos and video clips of the exact person, company, product, or place named in a script, with each candidate checked by a vision model and scored before returning download links or capture commands. It also plans b-roll across a whole transcript, matching each moment to the words it plays over.
      4
      MIT