MetaTag Genie

MetaTag Genie is a macOS Stdio MCP service designed to write image metadata so macOS Spotlight can index and search photos more effectively. You can call it from AI agents or local applications via standard input/output using the MCP interface, enabling you to attach tags, descriptions, people, and locations to images managed on your machine.

How to use

You will run MetaTag Genie as an MCP server that communicates over Stdio. From your MCP client, connect using the JSON‑RPC based MCP protocol, then call the writeImageMetadata tool to attach metadata to image files. The server accepts metadata in a single structured payload and writes it to the image file so Spotlight can index it.

To integrate, arrange your client to launch the MetaTag Genie process and communicate through its standard input and output. You can invoke it directly with a simple command via a package runner, or use a wrapper to ensure the MCP handshake happens automatically.

The primary tool you will use is writeImageMetadata. Use it to supply a target file path and a metadata block containing tags, a description, people, and a location. Ensure the file path is an absolute path to the image you want to augment.

How to install

Prerequisites: you need Node.js 22.x LTS or higher installed on your system.

Option 1: install via Smithery for automatic client installation and integration with Claude Desktop.

# Install via Smithery for the Claude client
npx -y @smithery/cli install @terryso/metatag_genie --client claude

Option 2: install globally with npm. This makes metatag-genie available as a CLI tool.

npm install -g metatag-genie

Option 3: run without installing globally using npx. This is the recommended approach for client integrations.

npx metatag-genie

Option 4: run directly from source after cloning, installing dependencies, and building.

# 1) Clone the repo
git clone <repository-url>
cd metatag-genie

# 2) Install dependencies
npm install
# or: yarn install

# 3) Build TypeScript to JavaScript
npm run build
# or: yarn build

# 4) Local test run (optional)
npm link

Additional notes

In client configurations that reference MCP integration, you can also launch the server via a standard MCP invocation like npx with arguments. For example, you can start a local stdio MCP server using the following approach.

{
  "mcpServers": {
    "MetaTagGenie": {
      "type": "stdio",
      "name": "metatag_genie",
      "command": "npx",
      "args": ["-y", "metatag-genie"]
    }
  }
}

Available tools

writeImageMetadata

Writes image metadata to a file, including tags, description, people, and location. This enables Spotlight indexing and improved searchability of images.