MetaTag Genie is a macOS Stdio MCP service for writing and managing image metadata to enhance Spotlight search.
Write metadata to images: Add tags, descriptions, people names, and locations to JPG, PNG, and HEIC files
Enhance searchability: Embedded metadata is indexed by macOS Spotlight, improving search capabilities
Standardized communication: Uses JSON-RPC protocol over standard input/output (Stdio) with MCP compliance
Flexible integration: Can be invoked via NPX, CLI, or directly from AI agent configurations
Customizable options: Allows specifying metadata fields with optional overwrite flag for existing metadata
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MetaTag Genie add tags 'vacation' and 'beach' to my Hawaii photo.jpg"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MetaTag Genie 是一个 macOS Stdio MCP 服务，专为写入图片元数据以增强 Spotlight 搜索而设计。该服务可被 AI 代理或其他需要本地管理图片元数据的应用程序调用，通过标准输入输出（Stdio）与客户端通信，提供符合 MCP (Machine Comprehension Protocol) 规范的接口。
Related MCP server: Gyazo MCP Server
通过 Stdio 暴露符合 MCP 规范的服务
提供 writeImageMetadata MCP Tool
支持向 JPG, PNG, HEIC 图片写入元数据
支持的元数据类型：
标签 (Tags)
描述 (Description)
人物 (People - 作为关键词)
地点 (Location - 文本)
写入的元数据可被 macOS Spotlight 搜索
Node.js 版本：Node.js 22.x LTS 或更高版本
隐含依赖：本项目使用 exiftool-vendored，它会自动管理 ExifTool 的依赖
要自动将 MetaTag Genie 安装到 Claude Desktop，请使用 Smithery：
npx -y @smithery/cli install @terryso/metatag_genie --client claude# 全局安装
npm install -g metatag-genie使用全局安装后，可以通过以下命令直接运行：
metatag-genie或者，您可以不安装直接使用npx运行：
npx metatag-genie这种方式不需要全局安装，也是AI代理等客户端调用的推荐方式。
# 1. 克隆仓库
git clone <repository-url>
cd metatag-genie
# 2. 安装依赖
npm install
# 或者: yarn install
# 3. 编译 TypeScript 代码
npm run build
# 或者: yarn build
# 4. 本地链接（可选，用于测试npx和命令行调用）
npm link安装包后，可以直接通过npx运行：
npx metatag-genie这种方式不需要全局安装包，适合作为AI代理或其他客户端的调用方式。
开发过程中，可以直接使用TypeScript源码运行服务：
npm run start:dev此命令使用ts-node直接运行TypeScript代码，无需预先编译，适合快速开发和调试。
构建后，可以通过以下命令运行编译好的JavaScript代码：
npm start
# 或者直接: node dist/main.js服务启动后会监听标准输入输出（Stdio），等待MCP客户端连接并发送JSON-RPC消息。
AI代理（如Cursor）或其他客户端需要在其配置中指定命令的完整路径：
基于Node.js：/usr/local/bin/node /path/to/metatag-genie/dist/main.js
使用npx：/usr/local/bin/npx metatag-genie
注意：本服务不监听网络端口，仅通过标准输入输出通信。
在Cursor编辑器中，可以通过以下步骤集成MetaTag Genie：
在项目根目录创建.cursor/mcp.json文件
添加以下配置内容：
{
"mcpServers": {
"MetaTagGenie": {
"command": "npx",
"args": [
"-y",
"metatag-genie"
]
}
}
}配置完成后，Cursor中的AI助手将能够使用MetaTag Genie提供的writeImageMetadata工具，直接为图片添加元数据，增强Spotlight搜索体验。
通信基于 Stdio 上的 JSON-RPC 2.0 协议。
客户端需要先发送 initialize 请求，服务器响应 InitializeResult，然后客户端发送 initialized 通知完成握手。
JSON-RPC 请求示例:
{
"jsonrpc": "2.0",
"id": "request-id-123",
"method": "writeImageMetadata",
"params": {
"filePath": "/Users/username/Pictures/photo.jpg",
"metadata": {
"tags": ["Vacation", "Beach"],
"description": "Sunset view from the hotel.",
"people": ["Alice", "Bob"],
"location": "Hawaii, USA"
},
"overwrite": true
}
}JSON-RPC 成功响应示例:
{
"jsonrpc": "2.0",
"id": "request-id-123",
"result": {
"success": true,
"filePath": "/Users/username/Pictures/photo.jpg",
"message": "Metadata successfully written."
}
}注意：实际使用时 filePath 需要是有效的绝对路径。
完整的 Tool 参数、返回值和错误代码定义，请参阅 MCP Tools 定义文档。
# 运行所有单元测试和集成测试
npm test
# 或者: yarn test
# 在监视模式下运行测试
npm run test:watch
# 或者: yarn test:watch
# 运行测试并生成覆盖率报告 (输出到 coverage/ 目录)
npm run test:cov
# 或者: yarn test:cov关于不同测试层级的更多信息，请参阅 测试策略文档。
项目使用 ESLint 和 Prettier 强制代码风格，详细规范请参阅 编码规范文档。
请在提交代码前运行以下命令：
# 检查代码风格
npm run lint
# 自动格式化代码
npm run formatmaster 分支用于发布稳定版本
开发新功能或修复 Bug 时，从 master 创建特性分支（例如 feature/add-png-support 或 fix/handle-exiftool-error）
完成后提交 Pull Request (PR) 到 master 分支
PR 应包含清晰的描述，说明变更内容和原因
PR 需要通过所有 CI 检查 (Linting, Tests, Build)
鼓励进行代码审查
如需报告 Bug 或提出功能建议，请在项目的 Issue Tracker 中创建新的 Issue，并提供尽可能详细的信息。
本项目使用GitHub Actions进行持续集成和自动发布：
每次Push和PR会自动运行测试和构建
创建Release后会自动发布到NPM
提交PR时请确保通过所有CI检查。如需发布新版本：
更新package.json中的版本号
创建一个新的GitHub Release
GitHub Actions会自动将包发布到NPM
本项目采用 MIT 许可证。详情请参阅项目根目录下的 LICENSE 文件。
Writes metadata (tags, description, people, location) to an image file.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | ||
| metadata | Yes | ||
| overwrite | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but lacks critical behavioral details. It mentions writing metadata but doesn't disclose permissions needed, whether it modifies the file in-place, error handling, or side effects like backup creation. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded and appropriately sized, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with 3 parameters, nested objects, no output schema, and no annotations), the description is incomplete. It lacks details on behavioral traits, parameter usage, and expected outcomes, making it inadequate for safe and effective tool invocation by an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists metadata types (tags, description, people, location), which partially explains the 'metadata' parameter, but with 0% schema description coverage, it doesn't fully compensate. It doesn't mention 'filePath' or 'overwrite', leaving key parameters undocumented. Baseline 3 is given as it adds some value but not enough to cover the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('writes') and resource ('metadata to an image file'), specifying the types of metadata (tags, description, people, location). It's specific about what the tool does, though without sibling tools, differentiation isn't applicable, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool, such as prerequisites (e.g., file must exist), alternatives, or exclusions. It merely states the action without context, leaving the agent to infer usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
writeImageMetadataWith only one tool, there is no possibility of confusion or overlap between tools. The tool's purpose is clearly defined and distinct by default.
A single tool inherently has perfect naming consistency, as there are no other tools to compare it against. The name 'writeImageMetadata' follows a clear verb_noun pattern.
A single tool is often too few for a server's scope, suggesting limited functionality. While it might be appropriate for a very narrow task, it feels thin and may not cover related operations like reading or updating metadata.
The server appears to target image metadata management, but with only a write tool, there are significant gaps. Missing operations like reading metadata, updating existing metadata, or deleting metadata will likely cause agent failures in workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A TypeScript MCP server for Home Assistant, enabling programmatic management of entities, automati…
MCP server for Qwen Image 3 AI image generation
Personal MCP server for humans who create. Proof of authorship, license control.
MCP server for InsForge BaaS — database, storage, edge functions, and deployments
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/terryso/meta_tag_genie'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
