Icoustic

Docs/MCP

MCP

On the Mac, Icoustic can speak MCP (Model Context Protocol): connect an AI client you already trust and ask real questions of your collection. Icoustic does not upload your catalog and does not call a model vendor. The server listens on your Mac only.

MCP is included with Icoustic Full (and during the Full trial). Icoustic must stay open while a client uses MCP.

Give your AI the Icoustic skill

Download the Icoustic skill package so Cursor, Claude, or another AI knows how the app works — and how to use MCP tools safely. Full install steps and the zip download are on that page.

Enable in Icoustic

  1. Open Icoustic → Settings… → MCP
  2. Turn Enable MCP on
  3. Confirm status shows something like Listening on 127.0.0.1:8741
  4. Leave capability on Analyst (read-only) for analysis, or switch to Librarian to stage proposals

Disabling MCP stops the server and rotates the token. If you used Install before, use Install again so clients get the new token.

Connect a client

In Settings → MCP → Connect, prefer the install buttons — they merge only the icoustic entry and leave your other MCP servers alone.

Cursor

  1. Click Add to Cursor — Cursor opens an install prompt; approve icoustic. Or click Install into Cursor config to merge into ~/.cursor/mcp.json.
  2. Refresh MCP in Cursor if tools don’t appear.
  3. Ask: “Using Icoustic, how many tracks are in my library?”

Claude Desktop

  1. Install Node.js if needed (node -v) — Claude uses a local npx mcp-remote proxy because cloud connectors cannot reach 127.0.0.1.
  2. Click Install into Claude config.
  3. Fully quit and reopen Claude Desktop.
  4. Confirm icoustic is connected, then ask about your library.

ChatGPT Desktop

  1. Click Install into ChatGPT Desktop config — merges into ~/.codex/config.toml.
  2. If macOS shows a permission error, select config.toml (or the .codex folder) in the file picker once. Press ⌘⇧. if the folder is hidden.
  3. Restart ChatGPT Desktop / start a new session.

ChatGPT custom connectors

Not supported for local Icoustic MCP. ChatGPT web connectors only talk to public HTTPS endpoints from OpenAI’s cloud — they cannot reach loopback without a tunnel, and Icoustic does not ship tunnels. Use Cursor, Claude Desktop, or ChatGPT Desktop instead.

Analyst vs Librarian

  • Analyst — read-only: stats, search, missing metadata, genre audit, duplicate candidates, playlists, sources
  • Librarian — everything Analyst can do, plus propose_* tools that stage changes for review

Mutations are review-gated. Nothing is written to tags or your library until you approve it in the sidebar under MCP Actions — or until the model calls apply_proposal when Allow AI to apply proposals is on (default off).

Typical Librarian proposals include tag edits, artwork actions, playlists and smart playlists, marking compilations, duplicate resolution (index-remove only — files stay on disk), and rescans. Applied changes can be rolled back; every apply also keeps an index snapshot you can restore.

Troubleshooting

  • Unauthorized / 401 — token rotated; Show token or re-Install
  • Connection refused — Icoustic not running, or MCP toggle off
  • Tools missing — refresh MCP / restart the client after Install
  • Permission error saving ChatGPT config — select ~/.codex/config.toml in the open dialog once
  • ChatGPT connectors “can’t reach” — expected; use a desktop client above
  • Claude needs Node — install Node.js so npx works

Privacy

  • Traffic stays on 127.0.0.1 between the client (or mcp-remote) and Icoustic
  • Your AI client may send tool inputs and outputs to whatever model you chose — prefer a local model if you want zero third-party visibility of titles, artists, and paths
  • Icoustic itself does not collect or phone home MCP traffic

See also Privacy & Local-first and Metadata & Tag Write-back.