Img-License MCP
Searches Openverse for openly licensed images, returning candidates only when licence and attribution metadata can be read from the source.
Searches Pexels for stock photos when an API key is configured, filtering candidates by verified licence and minimum width.
Searches Pixabay for stock images when an API key is configured, with licence verification and size-aware filtering.
Searches Unsplash for stock photos when an access key is configured, applying licence and minimum-width filters and reporting downloadable versus original dimensions.
Searches Wikimedia Commons for images whose licences are read from source metadata, filters by commercial-use and modification rights and minimum size, and re-inspects Commons file URLs to verify licence, author, and dimensions.
Uploads prepared WebP images to a WordPress site via the REST API, writes alt text and provenance metadata, and can set the uploaded image as the featured image.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Img-License MCP
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 |
| Commons ( | Candidates with a readable licence, author, dimensions and discard counters |
| Commons | Re-reads the licence of one image, in any of its URL shapes |
| Pillow | Downloads, downscales (never upscales) and converts to WebP, with the real byte saving |
| — | The |
| WordPress REST | Uploads the file, writes |
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 .venvInstall 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.txtCopy .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 |
| HTTP identity. Without a descriptive UA, Wikimedia answers 403 | — (there is a default; set your own) |
| Unsplash source | |
| Pexels source | |
| Pixabay source | |
| National Park Service source | |
|
| 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.pyRelated 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 |
|
|
| Licence engine: source code → canonical licence |
| One adapter per source, plus the registry of which key each one needs |
| Downloads, Commons thumbnails and Pillow helpers |
| Credentials and the provenance block |
| 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 |
| str | — | What the photo should show. English works best: most source metadata is in English |
|
|
| See below |
| int (0-10000) |
| Minimum width of the original. |
| list | all |
|
| int (1-50) |
| Candidates returned, already filtered and de-duplicated |
The three licence filters:
Value | Lets through | When to use it |
| Public domain, CC0, CC BY, CC BY-SA | The default. Commercial use and the right to modify, which resizing and cropping require |
| Public domain, CC0, stock licences | When you don't want to maintain credit lines. Far fewer results |
| 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 |
|
|
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 |
| Its licence code could not be read or is not citable (GFDL, Free Art License, |
| TIFF and friends: Commons' |
| Readable licence outside the filter (an NC licence with |
| Below |
| 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 |
|
|
|
|
|
|
|
|
|
{
"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 |
| str | — |
| int (64-5000) |
|
|
|
|
| int (1-100) |
|
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.webpNote 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 withoptimize+progressivecompresses 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 |
| yes | The output of |
| yes | Media library title |
| yes | In the site's language. You write it: nothing here invents it |
| yes | Go into the provenance block |
| yes | Resolution of the original, before resizing |
| no | The credit paragraph goes here when the licence requires it |
| no | Free text prepended to the provenance |
| no | Post ID |
| no | Sets the featured image. Requires |
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-06The 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.renderedshowsOriginal resolution: 6558×4372, with a multiplication sign. That is WordPress'swptexturize, which turns anxbetween numbers into×when rendering. The stored value keeps thexthat was sent. WordPress also prepends a<p class="attachment">with the thumbnail to the rendered description; your text comes after it.
Suggested workflow
search_images("santorini blue domes at sunset")→ pick a candidate.inspect_image(source_page_url)if it came from elsewhere and you want to re-confirm.prepare_image(file_url)→ checksaving_pctand thewarnings.build_attribution(...)ifattribution_requiredistrue.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, setIMG_LICENSE_USER_AGENTto your own descriptive UA with a contact.Commons only serves the widths in its bucket list. Building
/thumb/.../1600px-X.jpggives 400; 1280 and 1920 give 200. That is why no thumbnail URL is ever built by hand here: it is requested from the API withiiurlwidth, which rounds up to the next valid bucket.The Commons API misreports
thumbwidth(2026-09-06): withiiurlwidth=1600it answersthumbwidth: 1600x960, but thethumburlit hands over is the1920px-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_sizemax 20 (2026-09-06). With 21 it returns401 "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_pctreports.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
1536x850derivative 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, butfullHDURL(1920) andimageURL(original) are not returned unless Pixabay approves full access; the only downloadable field islargeImageURL, scaled to 1280 on its longest side. In practice, with the defaultmin_widthof 1600, Pixabay contributes nothing (all of it lands indiscarded_too_small). To use it, request full access or search withmin_width=1280.The NPS API publishes no dimensions. Without them every photo fell into
discarded_unknown_sizeand 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=maxcaps the WIDTH, not the longest side. Mixing them up swaps the figures on portrait photos: a 3024x4032 original served withw=2400is 2400x3200, not 1800x2400.WordPress has no media trash by default (
MEDIA_TRASHis off): a RESTDELETEwithoutforcefails, and with?force=trueit 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:imagedoes not refresh on the first try whenfeatured_mediachanges 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_mediaog:imageJSON-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:imagedoes not. That is whyset_featuredrepeats the same POST on purpose; on a site without Yoast the second request is harmless. Even so, check theog:imageof 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_wordpresswas tested end to end against a live WordPress site (2026-09-07): a plain media upload, and an upload withattach_to_post+set_featuredon a draft, checking afterwards through the API thatfeatured_media, Yoast'sog:imageand the JSON-LD all pointed at the right image.inspect_imageonly 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_locationfield is exposed in the results, but the server does not call it yet.Openverse sometimes returns
width/heightasnull. With a non-zeromin_widththose candidates fall intodiscarded_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.svgThe 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search and license documentary photos. AI agents pay on their own with a prepaid wallet key.
Image search for AI agents: 1.85M openly licensed images with source, license and attribution.
Image processing for AI agents: resize, convert, compress, crop, and web-ready AI-generated images.
Generate GEO/AEO-optimized articles and publish them to WordPress from your AI agent.
Related MCP Servers
- AlicenseAqualityCmaintenanceLicense-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.73MIT
- FlicenseBqualityDmaintenanceEnables searching and retrieving images from Wikipedia Commons with detailed metadata including licenses and authors.211-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to search, recommend, and deliver professional stock photos from Unsplash with intelligent context awareness and automatic attribution management.22 npm64MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.4MIT