--- title: Beeper Desktop MCP - Beeper Developer Docs description: Connect Beeper Desktop with AI assistants via Model Context Protocol lastUpdated: 2026-02-23T00:29:17.000Z --- 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](https://modelcontextprotocol.io/docs/getting-started/intro) **Beeper MCP runs on your device and requires Beeper Desktop to be running.** ## Quick start 1. **[Install Beeper Desktop](https://www.beeper.com/download)** 2. **Enable & Start Beeper Desktop API** [Enable Beeper Desktop API](beeper://connect) If the button above doesn’t work, open **Settings** → **Developers** and toggle **Beeper Desktop API** to enable it. 3. **Connect your MCP client** [Claude Desktop ](https://misc-assets.beeper.com/connect-files/BeeperDesktop.dxt) [Cursor ](cursor://anysphere.cursor-deeplink/mcp/install?name=beeper\&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0OjIzMzczL3YwL21jcCJ9) [Visual Studio Code ](vscode:mcp/install?%7B%22name%22%3A%22Beeper%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22http%3A%2F%2Flocalhost%3A23373%2Fv0%2Fmcp%22%7D) [Raycast ](raycast://mcp/install?%7B%22name%22%3A%22Beeper%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22http%3A%2F%2Flocalhost%3A23373%2Fv0%2Fmcp%22%7D) 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. 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](./auth) 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": [ "@beeper/mcp-remote", "--header", "Authorization: Bearer YOUR_TOKEN_HERE" ] } } } ``` ### Client-specific instructions **Cursor** [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=beeper\&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0OjIzMzczL3YwL21jcCJ9) 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](https://docs.anthropic.com/en/docs/claude-code/mcp). **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: CLI Server (Command) ``` { "beeper": { "command": "npx", "args": [ "@beeper/mcp-remote" ] } } ``` Read more on Warp’s [official documentation](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server). **Visual Studio Code** You can use [this link](vscode:mcp/install?%7B%22name%22%3A%22Beeper%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22http%3A%2F%2Flocalhost%3A23373%2Fv0%2Fmcp%22%7D) 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](https://code.visualstudio.com/docs/copilot/customization/mcp-servers). **Windsurf** **Configuration file:** `~/.codeium/windsurf/mcp_config.json` \~/.codeium/windsurf/mcp\_config.json ``` { "mcpServers": { "beeper": { "url": "http://localhost:23373/v0/mcp" } } } ``` Read more on Windsurf’s [official documentation](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin). **Codex** Prerequisite Using Beeper MCP server with Codex requires `node` to be installed on your system. **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](#tab-panel-6) - [Windows](#tab-panel-7) 1. **Download installer**: → 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. 1) **Download installer**: → 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. **Configuration file:** `~/.codex/config.toml` \~/.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](https://docs.codex.so/reference/configuration#mcp_servers). **Gemini CLI** **Add via 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` settings.json ``` { "mcpServers": { "beeper": { "httpUrl": "http://localhost:23373/v0/mcp", "timeout": 30000 } } } ``` Read more on Gemini CLI’s [official documentation](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html). **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](#tab-panel-8) - [Windows](#tab-panel-9) 1. **Download installer**: → 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. 1) **Download installer**: → 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": [ "@beeper/mcp-remote" ] } } } ```