# Banjo MCP server

> A self-hosted AI assistant that makes and receives phone calls to book appointments, handle errands, and answer inquiries.

- Repository: https://github.com/shatch/banjo
- Page: https://hostedmcp.org/servers/shatch/banjo
- Transport: remote
- Stars: 3
- License: MIT
- Latest version: 0.1.23

## Install

### Claude Code

```sh
claude mcp add --env 'DATABASE_URL=<YOUR_DATABASE_URL>' --env 'MCP_API_KEY=<YOUR_MCP_API_KEY>' --env 'TWILIO_AUTH_TOKEN=<YOUR_TWILIO_AUTH_TOKEN>' --env 'ASSISTANT_PRINCIPAL_NAME=<ASSISTANT_PRINCIPAL_NAME>' --env 'PUBLIC_HOSTNAME=<PUBLIC_HOSTNAME>' --env 'TWILIO_ACCOUNT_SID=<TWILIO_ACCOUNT_SID>' --env 'TWILIO_PHONE_NUMBER=<TWILIO_PHONE_NUMBER>' --env 'VOICE_AI_PROVIDER=<VOICE_AI_PROVIDER>' --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' banjo -- docker run -i --rm ghcr.io/shatch/banjo:0.1.23
```

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

```json
{
  "mcpServers": {
    "banjo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/shatch/banjo:0.1.23"
      ],
      "env": {
        "DATABASE_URL": "<YOUR_DATABASE_URL>",
        "MCP_API_KEY": "<YOUR_MCP_API_KEY>",
        "TWILIO_AUTH_TOKEN": "<YOUR_TWILIO_AUTH_TOKEN>",
        "ASSISTANT_PRINCIPAL_NAME": "<ASSISTANT_PRINCIPAL_NAME>",
        "PUBLIC_HOSTNAME": "<PUBLIC_HOSTNAME>",
        "TWILIO_ACCOUNT_SID": "<TWILIO_ACCOUNT_SID>",
        "TWILIO_PHONE_NUMBER": "<TWILIO_PHONE_NUMBER>",
        "VOICE_AI_PROVIDER": "<VOICE_AI_PROVIDER>",
        "OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
      }
    }
  }
}
```

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

```json
{
  "servers": {
    "banjo": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/shatch/banjo:0.1.23"
      ],
      "env": {
        "DATABASE_URL": "<YOUR_DATABASE_URL>",
        "MCP_API_KEY": "<YOUR_MCP_API_KEY>",
        "TWILIO_AUTH_TOKEN": "<YOUR_TWILIO_AUTH_TOKEN>",
        "ASSISTANT_PRINCIPAL_NAME": "<ASSISTANT_PRINCIPAL_NAME>",
        "PUBLIC_HOSTNAME": "<PUBLIC_HOSTNAME>",
        "TWILIO_ACCOUNT_SID": "<TWILIO_ACCOUNT_SID>",
        "TWILIO_PHONE_NUMBER": "<TWILIO_PHONE_NUMBER>",
        "VOICE_AI_PROVIDER": "<VOICE_AI_PROVIDER>",
        "OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"banjo","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/shatch/banjo:0.1.23"],"env":{"DATABASE_URL":"<YOUR_DATABASE_URL>","MCP_API_KEY":"<YOUR_MCP_API_KEY>","TWILIO_AUTH_TOKEN":"<YOUR_TWILIO_AUTH_TOKEN>","ASSISTANT_PRINCIPAL_NAME":"<ASSISTANT_PRINCIPAL_NAME>","PUBLIC_HOSTNAME":"<PUBLIC_HOSTNAME>","TWILIO_ACCOUNT_SID":"<TWILIO_ACCOUNT_SID>","TWILIO_PHONE_NUMBER":"<TWILIO_PHONE_NUMBER>","VOICE_AI_PROVIDER":"<VOICE_AI_PROVIDER>","OPENAI_API_KEY":"<YOUR_OPENAI_API_KEY>"}}'
```

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

```json
{
  "mcpServers": {
    "banjo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/shatch/banjo:0.1.23"
      ],
      "env": {
        "DATABASE_URL": "<YOUR_DATABASE_URL>",
        "MCP_API_KEY": "<YOUR_MCP_API_KEY>",
        "TWILIO_AUTH_TOKEN": "<YOUR_TWILIO_AUTH_TOKEN>",
        "ASSISTANT_PRINCIPAL_NAME": "<ASSISTANT_PRINCIPAL_NAME>",
        "PUBLIC_HOSTNAME": "<PUBLIC_HOSTNAME>",
        "TWILIO_ACCOUNT_SID": "<TWILIO_ACCOUNT_SID>",
        "TWILIO_PHONE_NUMBER": "<TWILIO_PHONE_NUMBER>",
        "VOICE_AI_PROVIDER": "<VOICE_AI_PROVIDER>",
        "OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add banjo --env 'DATABASE_URL=<YOUR_DATABASE_URL>' --env 'MCP_API_KEY=<YOUR_MCP_API_KEY>' --env 'TWILIO_AUTH_TOKEN=<YOUR_TWILIO_AUTH_TOKEN>' --env 'ASSISTANT_PRINCIPAL_NAME=<ASSISTANT_PRINCIPAL_NAME>' --env 'PUBLIC_HOSTNAME=<PUBLIC_HOSTNAME>' --env 'TWILIO_ACCOUNT_SID=<TWILIO_ACCOUNT_SID>' --env 'TWILIO_PHONE_NUMBER=<TWILIO_PHONE_NUMBER>' --env 'VOICE_AI_PROVIDER=<VOICE_AI_PROVIDER>' --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' -- docker run -i --rm ghcr.io/shatch/banjo:0.1.23
```

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

```toml
[mcp_servers.banjo]
command = "docker"
args = ["run", "-i", "--rm", "ghcr.io/shatch/banjo:0.1.23"]

[mcp_servers.banjo.env]
DATABASE_URL = "<YOUR_DATABASE_URL>"
MCP_API_KEY = "<YOUR_MCP_API_KEY>"
TWILIO_AUTH_TOKEN = "<YOUR_TWILIO_AUTH_TOKEN>"
ASSISTANT_PRINCIPAL_NAME = "<ASSISTANT_PRINCIPAL_NAME>"
PUBLIC_HOSTNAME = "<PUBLIC_HOSTNAME>"
TWILIO_ACCOUNT_SID = "<TWILIO_ACCOUNT_SID>"
TWILIO_PHONE_NUMBER = "<TWILIO_PHONE_NUMBER>"
VOICE_AI_PROVIDER = "<VOICE_AI_PROVIDER>"
OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'DATABASE_URL=<YOUR_DATABASE_URL>' -e 'MCP_API_KEY=<YOUR_MCP_API_KEY>' -e 'TWILIO_AUTH_TOKEN=<YOUR_TWILIO_AUTH_TOKEN>' -e 'ASSISTANT_PRINCIPAL_NAME=<ASSISTANT_PRINCIPAL_NAME>' -e 'PUBLIC_HOSTNAME=<PUBLIC_HOSTNAME>' -e 'TWILIO_ACCOUNT_SID=<TWILIO_ACCOUNT_SID>' -e 'TWILIO_PHONE_NUMBER=<TWILIO_PHONE_NUMBER>' -e 'VOICE_AI_PROVIDER=<VOICE_AI_PROVIDER>' -e 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' banjo docker -- run -i --rm ghcr.io/shatch/banjo:0.1.23
```

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

```json
{
  "mcpServers": {
    "banjo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/shatch/banjo:0.1.23"
      ],
      "env": {
        "DATABASE_URL": "<YOUR_DATABASE_URL>",
        "MCP_API_KEY": "<YOUR_MCP_API_KEY>",
        "TWILIO_AUTH_TOKEN": "<YOUR_TWILIO_AUTH_TOKEN>",
        "ASSISTANT_PRINCIPAL_NAME": "<ASSISTANT_PRINCIPAL_NAME>",
        "PUBLIC_HOSTNAME": "<PUBLIC_HOSTNAME>",
        "TWILIO_ACCOUNT_SID": "<TWILIO_ACCOUNT_SID>",
        "TWILIO_PHONE_NUMBER": "<TWILIO_PHONE_NUMBER>",
        "VOICE_AI_PROVIDER": "<VOICE_AI_PROVIDER>",
        "OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `DATABASE_URL` | yes | yes | Postgres connection URL. Migrations run on boot. |
| `MCP_API_KEY` | yes | yes | Bearer token MCP clients must send (at least 32 characters, e.g. openssl rand -hex 32). |
| `TWILIO_AUTH_TOKEN` | yes | yes | Twilio auth token. |
| `ASSISTANT_PRINCIPAL_NAME` | yes | no | The name of the person Banjo calls on behalf of. |
| `PUBLIC_HOSTNAME` | yes | no | Public hostname Twilio reaches this server on (no scheme), e.g. a tunnel or reverse proxy. |
| `TWILIO_ACCOUNT_SID` | yes | no | Twilio account SID. |
| `TWILIO_PHONE_NUMBER` | yes | no | The Twilio number Banjo calls from, in E.164 (+15551234567). |
| `VOICE_AI_PROVIDER` | yes | no | Voice AI vendor. openai is the one carrying live traffic. |
| `OPENAI_API_KEY` | no | yes | OpenAI API key, for VOICE_AI_PROVIDER=openai or openai-live. |
| `NOTIFICATION_CHANNEL` | no | no | How Banjo tells you a call's outcome. twilio_sms also needs NOTIFY_TO_PHONE_NUMBER and NOTIFY_FROM_PHONE_NUMBER; pushover needs PUSHOVER_APP_TOKEN and PUSHOVER_USER_KEY. |

## FAQ

### How does Banjo handle appointments?

It negotiates times against your Google Calendar or CalDAV calendars (like Fastmail or iCloud) and only confirms a booking after receiving a clear yes.

### Can Banjo handle phone menus and hold queues?

Yes, it can press digits to navigate phone menus and will wait silently in a hold queue for up to a specified number of minutes.

### Does Banjo disclose that it is an AI?

Yes, every outbound call begins with a mandatory disclosure line stating that it is an AI.

### Can Banjo answer incoming calls?

Yes, it features an optional inbound line that allows people to book, check, or reschedule appointments, and it can recognize callers from your contacts.
