metadata_mcp

Author: Jim Lehmer
License: MIT

A Model Context Protocol (MCP) server that reads and writes file metadata across a broad range of formats. Connect it to any MCP-compatible LLM client (Claude Desktop, Claude Code, etc.) and ask the model to read or write metadata on images, audio, video, documents, and text files — no knowledge of ExifTool, mutagen, or YAML required.

Why the name?

This server started as a thin ExifTool wrapper. It has since grown backends for audio formats ExifTool can't write (mutagen) and text-based formats with no binary metadata section (HTML, Markdown). "exiftool_mcp" no longer described it; "metadata_mcp" does.

Backend Architecture

The server dispatches automatically to the right backend based on file extension. You never need to specify which backend to use.

ExifTool

Handles the widest range of formats. Required for reading metadata from any format and for writing to images, video, and PDF. Must be installed separately and on PATH.

mutagen

Used for audio formats ExifTool can write only partially or not at all. Installed as a Python dependency in the server venv. Tag names are mapped to the appropriate ID3v2 frame (MP3) or used verbatim as Vorbis comment keys (OGG/Opus).

ID3v2 tag name map (MP3):

In-process text handlers

For formats with no binary metadata section:

• HTML: injects or updates a <meta name="..." content="..."> tag before </head>. The ExifTool tag name is mapped to a standard HTML meta name (Comment → description, etc.); unknown tags are lowercased and used verbatim.

• Markdown: writes or updates a YAML frontmatter block (--- ... ---) at the top of the file. The tag name is lowercased directly as the YAML key — no fixed mapping, any attribute works.

Bulk Operations

ExifTool-backed tools accept glob patterns and directory paths natively — ExifTool handles the expansion. This covers read_metadata, set_copyright, strip_metadata, set_author, set_description, set_gps, copy_metadata, and write_metadata for images/video/PDF.

For write_metadata on audio (MP3/OGG/Opus) and text (HTML/Markdown) formats, the server expands globs in Python before dispatching to the format-specific backend. All bulk operations happen in a single tool call — no loop needed.

# Read metadata from every photo — one call, no loop
read_metadata(path="photos/*.jpg")

# Set copyright on every photo — one call, no loop
set_copyright(path="photos/*.jpg", copyright="© 2026 Jim Lehmer")

# Strip metadata from every export — one call, no loop
strip_metadata(path="exports/*.jpg")

# Write ID3 tags to every MP3 — one call, no loop
write_metadata(path="music/*.mp3", tags={"Artist": "Jim Lehmer", "Album": "Demo"})

# Write EXIF to every JPEG — one call, no loop
write_metadata(path="photos/*.jpg", tags={"Copyright": "© 2026"})

# Recursive operation via passthrough
exiftool_passthrough(arguments=["-r", "-all=", "exports/"])

Tools

read_metadata

Read all metadata tags from any file. Uses ExifTool.

write_metadata

Write arbitrary tag=value pairs to a file. Backend is chosen automatically.

set_copyright

Set Copyright tag on a file or directory (ExifTool). Recursive flag available.

set_author

Set Author tag (ExifTool).

set_description

Set Description tag (ExifTool).

set_gps

Set GPS coordinates (ExifTool).

copy_metadata

Copy metadata from source to destination (ExifTool).

strip_metadata

Strip all metadata from a file or directory (ExifTool).

exiftool_passthrough

Run arbitrary ExifTool CLI commands for operations not covered by the tools above.

Requirements

• Python 3.10+

• ExifTool installed and on PATH

• Python packages: mcp[cli], mutagen (see requirements.txt)

Installation

git clone https://github.com/dullroar/metadata_mcp.git
cd metadata_mcp

python -m venv .venv
source .venv/bin/activate      # macOS/Linux
# .venv\Scripts\activate       # Windows

pip install -r requirements.txt

MCP Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "metadata": {
      "command": "/path/to/metadata_mcp/.venv/bin/python",
      "args": ["/path/to/metadata_mcp/server.py"]
    }
  }
}

Claude Code

claude mcp add metadata -- /path/to/metadata_mcp/.venv/bin/python /path/to/metadata_mcp/server.py

HTTP/SSE mode

python server.py --transport sse
# Listening on http://127.0.0.1:8000/sse

Example Prompts

• "Read all the metadata from this photo and tell me what camera was used."

• "Read the metadata from every photo in photos/ and summarize what cameras were used."

• "Set the Comment field on this MP3 to 'ripped from vinyl'."

• "Set the Artist and Album on every MP3 in music/ to 'Jim Lehmer' and 'Demo'."

• "Add an Author and Copyright field to this Markdown file."

• "Inject a description meta tag into this HTML page."

• "Set copyright on every JPEG in photos/ to '© 2026 Jim Lehmer'."

• "Copy all metadata from original.jpg to backup.jpg."

• "Strip all metadata from this file before uploading."

• "Strip all metadata from every JPEG in exports/ before I upload them."

• "Set my GPS coordinates on this photo to geotag my travels."

Testing with the MCP Inspector

mcp dev server.py

License

MIT — see LICENSE.