# Ventriloquist MCP server

> Turns Mac applications into MCP tools by replaying accessibility tree actions, allowing AI agents to interact with apps without screenshots.

- Repository: https://github.com/ShaanGS/ventriloquist
- Page: https://hostedmcp.org/servers/shaangs/ventriloquist
- Transport: stdio
- Stars: 5
- License: MIT
- Latest version: 0.5.0

## Install

### Claude Code

```sh
claude mcp add ventriloquist -- uvx ventriloquist-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "ventriloquist": {
      "command": "uvx",
      "args": [
        "ventriloquist-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "ventriloquist": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "ventriloquist-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"ventriloquist","type":"stdio","command":"uvx","args":["ventriloquist-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "ventriloquist": {
      "command": "uvx",
      "args": [
        "ventriloquist-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add ventriloquist -- uvx ventriloquist-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.ventriloquist]
command = "uvx"
args = ["ventriloquist-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user ventriloquist uvx -- ventriloquist-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "ventriloquist": {
      "command": "uvx",
      "args": [
        "ventriloquist-mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `VENT_ALLOW_HIGH` | no | no | Set to 1 to run tools a pack marks as high risk without asking. Without it, they're offered only to clients that can ask you to confirm each call (MCP elicitation). |
| `VENT_HEAL` | no | no | Set to 1 to let the server call a model to re-ground broken anchors. Off keeps serving model-free. |
| `VENT_HOME` | no | no | Directory for your own packs and traces. Defaults to ~/.ventriloquist. |
| `VENT_LIVE` | no | no | Set to 1 for live mode: the agent can look at and use any running app through its accessibility tree, and save steps that worked as a tool once you approve them. Sends, deletes and the like ask you first. |
| `VENT_NO_VALUES` | no | no | Set to 1, together with VENT_HEAL=1, to keep field values out of what the healer sends to the model. |
| `VENT_READ_ONLY` | no | no | Set to 1 to serve read-only tools only. Every other call is refused, even with VENT_ALLOW_HIGH. |

## FAQ

### How does Ventriloquist work differently from Claude's computer use?

Instead of using screenshots and model decisions for every step, Ventriloquist uses recorded steps on elements in the app's accessibility tree, which reduces token usage and prevents wrong clicks.

### What permissions are required to use Ventriloquist?

The server requires macOS Accessibility permissions for the application that starts the MCP server (such as your terminal or Claude Desktop).

### Can I use Ventriloquist with apps that don't have pre-made tools?

Yes, you can use 'live mode' to let your agent explore the app's accessibility tree and then save those successful steps as a new tool.

### Does Ventriloquist handle sensitive information like passwords?

No, the server is designed to avoid interacting with sensitive areas like password fields or sign-in windows.