Beeper Desktop MCP

Beeper Desktop API includes a built-in MCP (Model Context Protocol) server, enabling seamless integration with AI assistants like Claude Desktop, Claude Code, Cursor, and more.

What is Model Context Protocol?

MCP is an open protocol that standardizes how applications provide context to large language models (LLMs). Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools. MCP enables you to build agents and complex workflows on top of LLMs and connects your models with the world.

Learn more about MCP

Beeper MCP runs on your device and requires Beeper Desktop to be running.

Quick Start

Install Beeper Desktop
Enable & Start Beeper Desktop API

Enable Beeper Desktop API

If the button above doesn’t work, open Settings → Developers and toggle Beeper Desktop API to enable it.
Connect your MCP client

Claude Desktop

Cursor

Visual Studio Code

Raycast

These and more options like Windsurf are available in Settings → Developers.

Manual setup

As long as your MCP client supports oAuth and Streamable HTTP, you just need to add the MCP server URL to your client and the authentication will be handled automatically.

http://localhost:23373/v0/mcp

Manually setting the token

If you are having issues with authentication, or want to skip the authentication process, you can create an access token manually. See the Authentication Guide for details on how to obtain tokens.

When used with the MCP server, MCP authentication is bypassed and the token is used directly.

Streamable HTTP with custom token

{
  "mcpServers": {
    "beeper": {
      "url": "http://localhost:23373/v0/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

stdio via mcp-remote with custom token

{
  "mcpServers": {
    "beeper": {
      "command": "npx",
      "args": [
        "@beeper/mcp-remote",
        "--header",
        "Authorization: Bearer YOUR_TOKEN_HERE"
      ]
    }
  }
}

Client specific instructions

Cursor

If you are running on different port, you can setup manually:

Configuration file: ~/.cursor/mcp.json

Streamable HTTP

{
  "mcpServers": {
    "beeper": {
      "url": "http://localhost:23373/v0/mcp"
    }
  }
}

Claude Code

Install globally:

claude mcp add beeper http://localhost:23373/v0/mcp -t http -s user

Install within a directory:

claude mcp add beeper http://localhost:23373/v0/mcp -t http -s local

With manual token:

claude mcp add beeper http://localhost:23373/v0/mcp -t http -H "Authorization: Bearer YOUR_TOKEN_HERE" -s user # or -s local

Read more on Claude Code’s official documentation.

Warp

You can navigate to the MCP servers page in any of the following ways:

From Warp Drive: under Personal > MCP Servers
From the Command Palette: search for Open MCP Servers
From the settings tab: Settings > AI > Manage MCP servers

Then click the + Add button and paste:

{
  "beeper": {
    "command": "npx",
    "args": [
      "@beeper/mcp-remote"
    ]
  }
}

Read more on Warp’s official documentation.

Visual Studio Code

You can use this link to install globally in VS Code.

Workspace or user configuration (mcp.json)

Create .vscode/mcp.json in your workspace, or open MCP: Open User Configuration to edit your profile mcp.json:

{
  "servers": {
    "beeper": {
      "type": "http",
      "url": "http://localhost:23373/v0/mcp"
    }
  }
}

Command line (code —add-mcp)

code --add-mcp "{"name":"beeper","type":"http","url":"http://localhost:23373/v0/mcp"}"

Read more on Visual Studio Code’s official documentation.

Windsurf

Configuration file: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "beeper": {
      "url": "http://localhost:23373/v0/mcp"
    }
  }
}

Read more on Windsurf’s official documentation.

Codex

How to install Node.js

Node.js lets you run JavaScript programming language outside a browser. Many modern tools depend on it.

macOS
Windows

Download installer: https://nodejs.org → click LTS.
Open the .pkg file and follow steps.
Open Terminal: press ⌘ + Space, type Terminal, hit Enter.
Type: node -v - You should see a version number.

Download installer: https://nodejs.org → click LTS.
Run the .msi file, keep defaults, finish.
Open Command Prompt: press Windows key, type cmd, hit Enter.
Type: node -v - You should see a version number.

That means Node.js is installed and in your PATH. You can now use the Beeper Desktop's MCP server with CLI-based MCP clients.

Configuration file: ~/.codex/config.toml

# IMPORTANT: the top-level key is 'mcp_servers' rather than 'mcpServers'.
[mcp_servers.beeper]
command = "npx"
args = ["@beeper/mcp-remote"]
# Optional: override the default 10s startup timeout
# startup_timeout_ms = 20_000

Read more on Codex’s official documentation.

Gemini CLI

Add via CLI:

gemini mcp add --transport http beeper http://localhost:23373/v0/mcp

Or configure manually in: ~/.gemini/settings.json or .gemini/settings.json

{
  "mcpServers": {
    "beeper": {
      "httpUrl": "http://localhost:23373/v0/mcp",
      "timeout": 30000
    }
  }
}

Read more on Gemini CLI’s official documentation.

stdio

How to install Node.js

Node.js lets you run JavaScript programming language outside a browser. Many modern tools depend on it.

macOS
Windows

Download installer: https://nodejs.org → click LTS.
Open the .pkg file and follow steps.
Open Terminal: press ⌘ + Space, type Terminal, hit Enter.
Type: node -v - You should see a version number.

Download installer: https://nodejs.org → click LTS.
Run the .msi file, keep defaults, finish.
Open Command Prompt: press Windows key, type cmd, hit Enter.
Type: node -v - You should see a version number.

That means Node.js is installed and in your PATH. You can now use the Beeper Desktop's MCP server with CLI-based MCP clients.

If your MCP client supports Streamable HTTP, prefer those instead of stdio.

{
  "mcpServers": {
    "beeper": {
      "command": "npx",
      "args": [
        "@beeper/mcp-remote"
      ]
    }
  }
}