mcp-osxphotos

<!-- markdownlint-disable MD013 MD004 MD007 MD029 MD030 MD032 -->

An MCP server for interacting with the osxphotos CLI tool.

This project provides Model Context Protocol tools around the open source project osxphotos.

This server provides a way for AI tools that support the Model Context Protocol (MCP) to interact with your Apple Photos library through the powerful osxphotos command-line tool.

Quick Index

• Prerequisites
• Installation and Setup
• Usage
• Using uvx (alternative)
• Testing
• Developer Documentation
  • Available Tools
• Configure with common MCP clients
  • Claude Desktop (macOS)
  • VS Code – Continue extension
  • Zed editor
  • gemini-cli (template)
• License
• Publishing

Prerequisites

This server executes the osxphotos CLI. The executable is discovered in this order:

1. If the environment variable OSXPHOTOS_BIN is set to an absolute path to the executable, that path is used.
2. Otherwise, the system PATH is searched (same environment as the process that launches this server).

If the executable cannot be found, tools will return a clear error message asking you to set OSXPHOTOS_BIN or update PATH.

Tip: Verify discovery with the osxphotos_health tool. It reports the resolved path, --version, and relevant environment variables. If you’re running this from an app that manages its own environment, ensure the directory that contains osxphotos is on PATH (use which osxphotos to find it), or set OSXPHOTOS_BIN to the absolute path explicitly.

Python version: This server targets Python >= 3.11. You can confirm the runtime with the python_version tool.

Environment configuration: This server loads a .env file if present (via python-dotenv). You can set OSXPHOTOS_BIN=/absolute/path/to/osxphotos there instead of wiring it into your client config.

Installation and Setup

1. Clone the repository (or create the project files):

   # (If you have the project files, you can skip this step)
   git clone <repository_url>
   cd mcp-osxphotos
   

2. Install dependencies with uv (optional for published usage):

   This project uses uv for package management. For local development:

   uv sync
   

Usage

To run the MCP server, execute the following command from the project's root directory:

Recommended (published package):

uvx mcp-osxphotos

This runs the published console script and starts the server over stdio.

Development (from local source):

# Run the FastMCP server directly (no banners printed to stdout)
uv --directory /absolute/path/to/mcp-osxphotos run python src/mcp_osxphotos/server.py

Using uvx (alternative)

If you prefer not to install anything locally, you can launch the server using uvx. This downloads and runs the package in an isolated environment (cached by uv).

uvx mcp-osxphotos

Notes:

• With uvx, you don’t need to install mcp[cli] into your venv. The mcp tool will be resolved automatically.
• For GUI clients (Claude, Continue, Zed, etc.), avoid wrapping the server with mcp dev because it prints human-readable banners to stdout, which will break JSON-RPC parsing in clients. Instead, run Python directly on src/mcp_osxphotos/server.py (examples below) or use the published console script mcp-osxphotos.

Environment management: uv vs .venv

You don’t need a pre-created .venv for the client configurations shown here. There are two supported ways to run:

• Use uv to provide the environment (recommended for GUI clients):

  • Example: uv --directory /path/to/mcp-osxphotos run python src/mcp_osxphotos/server.py
  • uv will run the server with the project’s dependencies resolved from your pyproject.toml/uv.lock without requiring you to manually activate a venv.
  • This is what the sample Gemini/Claude/Zed configs use; no extra install step is required.

• Use your own persistent venv (handy for running tests or local dev shells):

  • Create/populate it with uv sync (or your preferred tool), which will install the pinned dependencies into .venv/.
  • Point your client to the venv’s Python (e.g., /absolute/path/to/mcp-osxphotos/.venv/bin/python) and set the script to src/mcp_osxphotos/server.py.

Rule of thumb:

• If your client command starts with uv/uvx, you do not need extra installation steps; uv will handle resolving the environment for that run.
• If your client command starts with a bare python path, ensure that Python’s environment already has the project dependencies (use .venv/bin/python after uv sync).

Testing

Once the server is running, you can test it using the MCP Inspector, a web-based interface for interacting with the server's tools.

1. When you start the server, it will print a URL in your terminal, usually http://localhost:6274.
2. Open this URL in your web browser.
3. You will see all the available tools and their parameters.
4. You can expand each tool to see its parameters, fill them with test values, and click the "Execute" button to run the tool and see the output.

Configure with common MCP clients

Below are examples for wiring this server into popular MCP clients. For development, use an absolute path to src/mcp_osxphotos/server.py and run Python directly (do not use mcp dev in GUI clients). For published usage, prefer the console script mcp-osxphotos. Set OSXPHOTOS_BIN if your client is a GUI app (it may not inherit your shell PATH).

Tip: After adding a server, run python_version and osxphotos_health from your client to verify the environment.

Claude Desktop (macOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add an entry under mcpServers:

Dev config (local source):

{
    "mcpServers": {
        "mcp-osxphotos": {
            "command": "uv",
            "args": ["--directory", "/absolute/path/to/mcp-osxphotos", "run", "python", "src/mcp_osxphotos/server.py"],
            "env": {
                "OSXPHOTOS_BIN": "/absolute/path/to/osxphotos"
            }
        }
    }
}

Published config (recommended):

{
    "mcpServers": {
        "mcp-osxphotos": {
            "command": "uvx",
            "args": ["mcp-osxphotos"],
            "env": {
                "OSXPHOTOS_BIN": "/absolute/path/to/osxphotos"
            }
        }
    }
}

Then restart Claude Desktop.

VS Code – Continue extension

Create or edit ~/.continue/config.json (user-level) or .continue/config.json in your workspace:

Dev config (local source):

{
    "mcpServers": {
        "mcp-osxphotos": {
            "command": "uv",
            "args": ["--directory", "/absolute/path/to/mcp-osxphotos", "run", "python", "src/mcp_osxphotos/server.py"],
            "env": {
                "OSXPHOTOS_BIN": "/absolute/path/to/osxphotos"
            }
        }
    }
}

Or with published package:

{
    "mcpServers": {
        "mcp-osxphotos": {
            "command": "uvx",
            "args": ["mcp-osxphotos"],
            "env": {
                "OSXPHOTOS_BIN": "/absolute/path/to/osxphotos"
            }
        }
    }
}

Reload the Continue extension (or VS Code) and look for the server under Tools.

Zed editor

Add a server entry to your Zed settings (e.g., ~/.config/zed/settings.json). Insert under the root settings object:

Dev config (local source):

{
    "mcp": {
        "servers": [
            {
                "name": "mcp-osxphotos",
                "binary": "uv",
                "args": ["--directory", "/absolute/path/to/mcp-osxphotos", "run", "python", "src/mcp_osxphotos/server.py"],
                "env": { "OSXPHOTOS_BIN": "/absolute/path/to/osxphotos" }
            }
        ]
    }
}

Or with published package:

{
    "mcp": {
        "servers": [
            {
                "name": "mcp-osxphotos",
                "binary": "uvx",
                "args": ["mcp-osxphotos"],
                "env": { "OSXPHOTOS_BIN": "/absolute/path/to/osxphotos" }
            }
        ]
    }
}

Restart Zed to pick up changes.

gemini-cli (template)

If your gemini-cli supports MCP servers via a config file, the entry typically follows the same pattern as above. Use this as a template and consult the gemini-cli documentation for the exact config path and schema:

Dev config (local source):

{
    "mcpServers": {
        "mcp-osxphotos": {
            "command": "uv",
            "args": ["--directory", "/absolute/path/to/mcp-osxphotos", "run", "python", "src/mcp_osxphotos/server.py"],
            "env": { "OSXPHOTOS_BIN": "/absolute/path/to/osxphotos" }
        }
    }
}

Or with published package:

{
    "mcpServers": {
        "mcp-osxphotos": {
            "command": "uvx",
            "args": ["mcp-osxphotos"],
            "env": { "OSXPHOTOS_BIN": "/absolute/path/to/osxphotos" }
        }
    }
}

Troubleshooting tips:

• GUI apps often have a minimal PATH. Prefer setting OSXPHOTOS_BIN to the absolute path of osxphotos.
• Ensure your Python matches the supported range (>= 3.12,< 3.14). Use the python_version tool to verify.
• Use osxphotos_health to confirm the resolved CLI path and version.

Developer Documentation

See the full tool reference in docs: docs/available-tools.md.

Notes on interactive commands

The osxphotos commands inspect and repl are intentionally not exposed as MCP tools because they require interactive terminal control and real-time user interaction with Photos or a shell session. MCP tools run as single, stateless invocations and return outputs, which is not compatible with the continuous interactive behavior expected by these commands. If you need their functionality:

• For inspect, run it in a local terminal while using Photos for interactive selection.
• For repl, open the REPL in a terminal for exploratory work, then script repeatable logic and run it via the run tool.

How it Works

The tools in this server are wrappers around the osxphotos CLI tool. When you call a tool, the server constructs and executes the corresponding osxphotos command with the provided parameters. The output of the command is then returned to the client.

Extending the Server

You can easily extend the server by adding new tools or modifying the existing ones in src/mcp_osxphotos/server.py.

To add a new tool, simply define a new function and decorate it with @mcp.tool(). The function's name will be the tool's name, and its parameters will be the tool's parameters. Inside the function, you can use the subprocess module to execute any osxphotos command you want.

Debugging with MCP Inspector

For a great debugging experience, use the MCP Inspector:

• Published package:

  npx @modelcontextprotocol/inspector uvx mcp-osxphotos
  

• Local development (no banners):

  npx @modelcontextprotocol/inspector uv --directory /absolute/path/to/mcp-osxphotos run python src/mcp_osxphotos/server.py
  

The Inspector will display a URL you can open in your browser.

Warning:

• Avoid mcp dev when launching from GUI clients or inspector if your client parses stdout strictly as JSON-RPC. The mcp dev wrapper prints a human-readable banner to stdout which can cause errors like “Unexpected token … is not valid JSON”. Running the FastMCP server directly via python src/mcp_osxphotos/server.py avoids this.

Lockfile maintenance

If you change dependencies or project metadata, regenerate the lockfile:

uv sync

Smoke tests

A tiny unittest-based smoke test suite is included to sanity-check the environment and a couple of tools:

• python_version returns the running Python version and executable path.
• osxphotos_health reports whether the osxphotos CLI is discoverable and, if so, where.

Run the tests with uv:

# Ensure a compatible Python is pinned (project requires >=3.11)
uv python pin 3.12

# Run unittest discovery
uv run python -m unittest discover -s tests -p 'test*.py' -q

Notes:

• The tests don’t require osxphotos to be installed; they only report discovery status. If osxphotos is not found, the test still passes as long as osxphotos_health returns the expected JSON shape.
• The tests add src/ to sys.path so they work from a local checkout without installation.

Common pitfalls and troubleshooting

• ModuleNotFoundError: No module named 'mcp' when launching from a GUI:
  • Ensure you launch with a Python that has project dependencies available. Prefer:
    • command: absolute path to your venv’s Python, or
    • command: uv with args: ["--directory", "/path/to/mcp-osxphotos", "run", "python", "src/mcp_osxphotos/server.py"].
• JSON parse errors like “Unexpected token … is not valid JSON”:
  • Don’t use mcp dev in your GUI config. It prints banners to stdout. Launch the server directly.
• GUI apps often don’t inherit your PATH:
  • Set OSXPHOTOS_BIN to the absolute path for osxphotos.
  • Consider using absolute paths for uv, python, etc., in your client config.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Publishing

Looking to release a version users can run via uvx mcp-osxphotos?

• Dry run on TestPyPI: see docs/publishing-test.md
• Real release to PyPI: see docs/publishing.md