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, Codex, 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

1. Install Beeper Desktop and make sure it’s running.

2. Connect your MCP client

   Claude Desktop

   Cursor

   Visual Studio Code

   Raycast

   Additional options like Claude Code, Codex, Streamable HTTP, and stdio are available in Settings → Integrations.

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.

Streamable HTTP

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

With manual token

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

stdio via mcp-remote with custom token

With manual token

{
  "mcpServers": {
    "beeper": {
      "command": "npx",
      "args": [
        "-y",
        "@beeper/mcp-remote",
        "--header",
        "Authorization: Bearer ${ACCESS_TOKEN}"
      ],
      "env": {
        "ACCESS_TOKEN": "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

~/.cursor/mcp.json

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

Claude Code

Install globally:

Global installation

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

Install within a directory:

Directory installation

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

With manual token:

With 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.

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:

.vscode/mcp.json

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

Command line (code —add-mcp)

Add to VS Code via CLI

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

Read more on Visual Studio Code’s official documentation.

Codex

Add via CLI:

Add via CLI

codex mcp add beeper --url http://localhost:23373/v0/mcp

With manual token:

With token

export CODEX_BEEPER_TOKEN=YOUR_TOKEN_HERE
codex mcp add beeper --url http://localhost:23373/v0/mcp --bearer-token-env-var CODEX_BEEPER_TOKEN

Read more on Codex’s official documentation.

stdio

Prerequisite

Using Beeper MCP server with stdio requires node to be installed on your system. See instructions below. We are working on lifting this restriction.

How to install Node.js

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

macOS

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

Windows

1. Download installer: https://nodejs.org → click LTS.
2. Run the .msi file, keep defaults, finish.
3. Open Command Prompt: press Windows key, type cmd, hit Enter.
4. 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.

mcp.json

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