Connect AI Tools to Your Media Library

Sync Awesome includes a built-in MCP server that lets AI assistants search, browse, and organize your photos and videos.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI tools connect to external data sources. When you enable the MCP server in Sync Awesome, AI assistants can:

🔍

Search Your Media

Ask your AI to find photos by description, tags, people, or dates.

🏷️

Read Categories

Access AI-generated tags, detected objects, and people identifications.

📊

Get Library Stats

Ask about your collection size, recent uploads, and sync status.

👥

Browse People

Query identified people and their associated photos.

Prerequisites

Sync Awesome Desktop App

The MCP server runs inside the desktop app. Make sure it's installed and running.

Node.js or Bun

The MCP server requires a JavaScript runtime. Install either Node.js (v18+) or Bun on your Mac.

An MCP-compatible AI tool

Such as Claude Desktop, Cursor, Windsurf, or any other tool that supports MCP.

Step 1: Enable the MCP Server

Open the Sync Awesome desktop app
Go to Settings
Scroll to the MCP Server section
Toggle the switch to enable it

The app will automatically detect your Node.js or Bun installation, generate a secure API key, and start the MCP server. You'll see a green "Running" status when it's ready.

Tip: If you see a message that Node.js or Bun is required, install one of them and try again. Bun is recommended for faster startup.

Step 2: Copy Your Configuration

Once the MCP server is enabled, the Settings screen shows your personal MCP configuration with your unique API key. Click the Copy button to copy it to your clipboard.

This configuration contains your server URL and a unique API key that authenticates your AI tool with Sync Awesome. It looks something like this:

{
  "mcpServers": {
    "syncawesome": {
      "url": "http://localhost:23517/",
      "headers": {
        "X-Session-Key": "mcp_..."
      }
    }
  }
}

Important: Always copy the configuration from the Sync Awesome app rather than typing it manually. The app generates a unique API key for your machine.

Step 3: Paste Into Your AI Tool

After copying the configuration from Sync Awesome, paste it into your AI tool's MCP settings. Choose your tool below for specific instructions.

Claude Desktop

Open Claude Desktop
Go to Settings → Developer → Edit Config
This opens claude_desktop_config.json in your editor
Paste the configuration you copied from Sync Awesome
If the file already has other MCP servers, merge the "syncawesome" entry into the existing mcpServers object (don't replace the whole file)
Save the file and restart Claude Desktop

Config file location:

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Code (CLI)

Claude Code can connect to MCP servers via the command line. Copy the URL and API key from the Sync Awesome configuration, then run:

claude mcp add -t http \
  syncawesome <url from your config> \
  -H "X-Session-Key: <key from your config>"

Replace the URL and key values with the ones shown in the Sync Awesome Settings screen. You can also copy the full command directly from the app's Settings page.

Cursor

Create or edit .cursor/mcp.json in your project root (or any parent directory) and paste the configuration you copied from Sync Awesome.

Alternatively, use the Cursor Settings UI:

Open Cursor Settings (Cmd + ,)
Search for MCP
Click Add new MCP server
Set the type to HTTP
Enter the URL and API key from your Sync Awesome configuration

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json and paste the configuration you copied from Sync Awesome.

Note: Windsurf uses serverUrl instead of url. You may need to rename the key after pasting:

{
  "mcpServers": {
    "syncawesome": {
      "serverUrl": "...",  <-- rename "url" to "serverUrl"
      "headers": { ... }
    }
  }
}

Alternatively, use the Windsurf UI: Settings → Cascade → MCP Servers → Add Server, then choose HTTP and enter the URL and API key from your configuration.

VS Code (GitHub Copilot)

VS Code supports MCP servers through GitHub Copilot. Create or edit .vscode/mcp.json in your project and adapt the configuration from Sync Awesome to this format:

{
  "servers": {
    "syncawesome": {
      "type": "http",
      "url": "<url from your config>",
      "headers": {
        "X-Session-Key": "<key from your config>"
      }
    }
  }
}

Note that VS Code uses servers (not mcpServers) and requires a "type": "http" field.

Other MCP Clients

For any MCP-compatible tool, use the URL and API key from the Sync Awesome Settings screen:

TransportHTTP (Streamable HTTP)

URLShown in your copied configuration

Auth HeaderX-Session-Key with the value from your config

Default Port23517 (configurable in Settings)

Troubleshooting

My AI tool says "Failed to connect" or "Connection refused"

Check the MCP server is running: Open Sync Awesome Settings and look for the green "Running" status in the MCP Server section
Restart the MCP server: Toggle it off and on again in Settings
Check the port: Make sure no other application is using the same port
Restart your AI tool: Some tools need a restart after config changes

"Node.js or Bun is required" message

The MCP server needs a JavaScript runtime. Install one:

Bun (recommended): Open Terminal and run curl -fsSL https://bun.sh/install | bash
Node.js: Download from nodejs.org or install via Homebrew: brew install node

After installing, toggle the MCP server off and on again.

Authentication errors / "Unauthorized"

Your configuration may be outdated or pasted incorrectly.

Go to Sync Awesome Settings and click Copy to get a fresh configuration
Replace the entire configuration in your AI tool's config file
Make sure the X-Session-Key header and its value are present
Restart your AI tool after updating the config

The MCP server was running but stopped unexpectedly

The MCP server runs as a child process of the Sync Awesome app. It will stop if:

The Sync Awesome app is quit
You toggle the MCP server off in Settings
The Node.js/Bun process crashes

The MCP server restarts automatically when the app launches (if it was previously enabled). You can also restart it manually by toggling it off and on in Settings.

Can I change the MCP server port?

The default port is 23517. If you need to change it, update the port in the Sync Awesome Settings. After changing the port, copy the updated configuration and paste it into your AI tool.

Security and Privacy

The MCP server only runs on your local machine and is protected by a unique API key:

The server listens on localhost only — it cannot be accessed from other devices on your network
Every request requires a valid API key in the X-Session-Key header
Your API key is generated randomly and stored locally in the Sync Awesome database
No data is sent to the cloud — all communication stays between your AI tool and the Sync Awesome app on your machine

Need More Help?

Check out our general setup guide or contact us for support.

Setup Guide Report a Bug