Ventriloquist MCP server

Turn Mac apps into MCP tools your AI agent can call. Install · How it works · Packs · Security

About

Ventriloquist learns a Mac app once through the macOS accessibility API and keeps the actions worth having as typed tools, like outlookfiletoreceipts or texteditwrite_document. Your agent calls them over MCP, and every call replays the recorded steps: no screenshots and no vision model. The agent still decides which tool to call. It never decides where to click.

A real run on test emails, by an agent that hadn't seen the expected answers: 6 of 6 filed. The preview is sped up 25x; email 1 plays at real speed with the agent's pauses cut. <!-- mcp-name: io.github.ShaanGS/ventriloquist -->

Try it in a minute

Needs macOS and uv (brew install uv).

uv tool install ventriloquist-mcp
vent doctor

vent doctor checks the one permission vent needs. If it says Accessibility is missing, open System Settings > Privacy & Security > Accessibility, switch on your terminal app, restart the terminal, and run it again. (pipx install ventriloquist-mcp works too.)

Now drive TextEdit with the pack that ships with vent:

echo "hello" > /tmp/vent-demo.txt && open -a TextEdit /tmp/vent-demo.txt
vent run TextEdit write_document --arg text="typed by a pack"
vent run TextEdit read_document

The document changes with no keystrokes and no screenshot: the pack sets the text area's value through the accessibility API, then reads it back to verify. write_document replaces the whole text of the frontmost TextEdit document, which is why the first line opens a scratch file; don't run it with a document you care about in front.

Use it from Claude, Cursor, or Codex

vent serve speaks MCP over stdio. GUI apps start MCP servers without your shell's PATH, so the config needs vent's absolute path, and vent mcp-config prints the entry with the right path for your machine:

{
  "mcpServers": {
    "ventriloquist": {
      "command": "/Users/you/.local/bin/vent",
      "args": ["serve"]
    }
  }
}

~/Library/Application Support/Claude/claudedesktopconfig.json. Claude rewrites that file while it runs, so an edit made with it open gets lost.

• Claude Desktop: quit Claude, then merge it into

• Cursor: merge it into ~/.cursor/mcp.json.
• Claude Code: claude mcp add --scope user ventriloquist -- ~/.local/bin/vent serve
• Codex CLI: add to ~/.codex/config.toml:

[mcp_servers.ventriloquist]
  command = "/Users/you/.local/bin/vent"
  args = ["serve"]

The Accessibility permission belongs to whichever app starts vent serve: Cursor itself, or your terminal for Claude Code and Codex. Switch it on for that app (use the + button if it isn't in the list yet) and restart it.

Shortened. The full README is on GitHub.