wikimedia

Quick Start

Python 3.11 or newer is required. Install uv to create the project environment and install the optional MCP server dependency.

cd ~/Projects/wikimedia
uv sync --extra mcp
.venv/bin/wikimedia --help
.venv/bin/wikimedia search "Discogs logo" --type svg --limit 5

If the shell command is already installed, run wikimedia "Discogs logo" to open the interactive result picker. Use an exact Commons file title for repeatable downloads and references.

cd ~/Projects/wikimedia
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[mcp]"

Related MCP server: call-copilot

Features

Compatibility

The HTTP client uses Python's standard library. MCP support adds the optional mcp package. The project is developed and verified on macOS; platform entries describe the integrations present in the code.

Workflow

Interactive terminals show a numbered picker and action menu. In a non-interactive shell, a plain search prints results; a search combined with an action uses the first ranked result. Use an exact File: title when a script must target a specific item.

Usage

Search And Select

# Interactive search and selection in a terminal
wikimedia "Discogs logo"

# Filter for vector files and print structured results
wikimedia search "Discogs logo" --type svg --limit 5 --json

# Search for images, audio, video, or PDF files
wikimedia search "field recording" --type audio --limit 10

search is optional for a Commons query. The first example uses the interactive selector when stdin is a terminal. --json disables interactive output.

Inspect A File

wikimedia info "File:Discogs icon.svg"
wikimedia "https://commons.wikimedia.org/wiki/File:Discogs_icon.svg" --json

The record includes the Commons source page and direct media URL, file dimensions and size, MIME type, upload timestamp, artist, license fields, and restrictions such as trademark notices.

Create References

# Print a Markdown image reference
wikimedia md "File:Discogs icon.svg"

# Print an HTML image element with a display height
wikimedia html "File:Discogs icon.svg" --height 32

# Print the direct media URL or an attribution line
wikimedia url "File:Discogs icon.svg"
wikimedia attr "File:Discogs icon.svg"

# Copy a Markdown reference to the text clipboard
wikimedia md -c "File:Discogs icon.svg"

When l or url is used without a style, an interactive terminal offers Markdown, HTML, URL, and attribution formats. md, html, and attr select a format directly. A width requests a Wikimedia thumbnail, which may change an SVG reference into a PNG preview URL.

Download Media

# Download the original file to ./downloads
wikimedia d --out ./downloads "File:Discogs icon.svg"

# Download a 120 px preview. SVG previews are raster PNGs.
wikimedia d --out ./downloads --width 120 "File:Discogs icon.svg"

# Download and copy the downloaded file to the system clipboard
wikimedia d c --out ./downloads "File:Discogs icon.svg"

# Download, print a Markdown reference, and force replacement if needed
wikimedia d l md -f --out ./downloads "File:Discogs icon.svg"

Each download writes a sibling .wikimedia.json file with the source record, representation, retrieval time, byte count, and SHA-256 hash. Downloads are staged before publication and do not overwrite existing media or sidecars by default.

Browse Categories

wikimedia category "ITunes logos" --limit 10
wikimedia cat "Category:Discogs logos" --limit 20 --json

The category command lists direct file members, not recursive descendants. Use --cursor with the continuation token from JSON output to request another page.

Read Wikipedia

# Fetch an article introduction
wikimedia wiki "MediaWiki"

# Fetch the full plain-text extract or include revision wikitext
wikimedia wiki "MediaWiki" --full
wikimedia wiki "MediaWiki" --full --wikitext --language en

# Create a revision-specific Markdown citation
wikimedia wiki md "MediaWiki"

The CLI fetches a known article title. Wikipedia title search is available through the MCP wikipedia_search tool; the CLI does not currently expose a separate Wikipedia search command. wikipedia_list_images returns titles only. Some may be local Wikipedia files or non-free media, so a title alone does not establish that a Commons download is available.

Copy And Open

On macOS, file clipboard uses AppleScript and text clipboard uses pbcopy. On Linux, text clipboard tries wl-copy, xclip, then xsel; file clipboard falls back to copying the local path. Browser opening uses open on macOS and xdg-open on Linux.

Commands

Short actions can be separate words (d c) or grouped (-dcf). --out may appear before or after the query. The output-directory short flag is -O; -o is reserved for open.

MCP Server

Install the optional MCP dependency with uv sync --extra mcp. The server uses stdio and exposes nine tools for Commons search, file metadata, categories, references, downloads, Wikipedia articles, images, and citations.

# Start the standalone server with downloads disabled
.venv/bin/wikimedia-mcp

# Enable downloads under a fixed directory
.venv/bin/wikimedia-mcp --download-dir ~/Downloads/Wikimedia

# Or start it through the main CLI
.venv/bin/wikimedia mcp --download-dir ~/Downloads/Wikimedia

Add the executable to your MCP client's configuration. Use an absolute path to the checkout and choose a download directory the server may write to.

{
  "mcpServers": {
    "wikimedia": {
      "command": "/absolute/path/to/wikimedia/.venv/bin/wikimedia",
      "args": [
        "mcp",
        "--download-dir",
        "/absolute/path/to/wikimedia-downloads"
      ]
    }
  }
}

Downloads are disabled until a root is configured with --download-dir or WIKIMEDIA_DOWNLOAD_DIR. MCP downloads accept a relative subdir, validate path containment, and refuse to overwrite existing files.

Configuration

There is no configuration file or API key. The CLI reads these environment variables when present:

The CLI defaults downloads to the current directory. --out changes that location for a command; it does not enable MCP downloads.

Reuse And Safety

Wikimedia records can contain license, author, source, and restriction metadata. The tool carries that data into references and download sidecars, but it does not determine whether a particular reuse is lawful or whether a mark may be used commercially.

The header mark is Commons-logo.svg, by Reidab, Grunt, 3247, and Pumbaa. It is licensed under CC BY-SA 3.0 and is identified on Commons as a Wikimedia trademark. Its source record is preserved in assets/Commons-logo.svg.wikimedia.json; see the Commons file page.

The downloader only accepts HTTPS Wikimedia media hosts, follows redirects only to supported hosts, caps files at 100 MiB in the CLI, and checks the downloaded original size against the API record when available. --force replaces both the media file and sidecar.

How It Works

The CLI and MCP adapter share one Python core. Both query the same Wikimedia APIs and use the same reference formatter and downloader. The downloader writes a media file and a provenance sidecar. Network access uses Python's standard library; the MCP SDK is the only optional runtime dependency.

Troubleshooting

Install the optional server dependency from the project root:

uv sync --extra mcp

Choose another destination or filename. Add --force only when replacing both the media and its metadata sidecar is intended.

Some files have no preview URL at the requested size. Remove --width to use the original file, or try a smaller width.

On macOS, check that pbcopy and osascript are available. On Linux, install one of wl-copy, xclip, or xsel for text. File-item clipboard integration is macOS-specific.

Check network access and retry later. The client retries temporary API or transport failures, but honors long Retry-After pauses by returning an error rather than sleeping for an extended period.

Structure

wikimedia/
├── assets/
│   ├── Commons-logo.svg          # Wikimedia Commons source mark
│   ├── Commons-logo.svg.wikimedia.json # License and source record
│   ├── wikimedia-header.svg       # Repository header banner
│   ├── workflow.svg              # Wide workflow graphic
│   └── workflow-mobile.svg       # Mobile workflow graphic
├── bin/
│   └── wikimedia                 # Symlink-friendly development launcher
├── src/wikimedia_tool/
│   ├── cli.py                    # Command-line entry point
│   ├── client.py                 # Shared Wikimedia API client
│   ├── clipboard.py              # Clipboard and system-open helpers
│   ├── downloads.py              # Safe media transfer and provenance
│   ├── references.py             # Markdown, HTML, URL, attribution output
│   ├── server.py                 # Optional MCP stdio server
│   └── ui.py                     # Terminal cards and selectors
├── tests/
│   └── test_wikimedia.py         # Unit tests
├── downloads/                    # Local download examples and output
├── pyproject.toml                # Package metadata and entry points
└── uv.lock                       # Locked development environment

Development

uv sync --extra mcp
uv run python -m unittest discover -s tests -v
uv run wikimedia --help
uv build

The test suite uses the standard-library unittest runner. Tests mock network transfers; live API and download behavior should be checked separately when changing the HTTP client or downloader.

License

𝗗𝗢 𝗪𝗛𝗔𝗧 𝗧𝗛𝗘 𝗙𝗨𝗖𝗞 𝗬𝗢𝗨 𝗪𝗔𝗡𝗧 𝗧𝗢 𝗣𝗨𝗕𝗟𝗜𝗖 𝗟𝗜𝗖𝗘𝗡𝗦𝗘

𝗖𝗢𝗣𝗬𝗥𝗜𝗚𝗛𝗧 © 𝟮𝟬𝟮𝟲 𝗗𝗘𝗔𝗧𝗛𝗥𝗔𝗦𝗛𝗘𝗗