Give Gemini CLI Its Own iMessage Number With Beam

Gemini CLI has no phone of its own and no iMessage account. Point it at Beam and it gets a workspace to read and write against instead: real conversation history, a configurable assistant, and a number that sends iMessage to iPhones, RCS to Android phones that support it, and SMS everywhere else. Connecting the two takes a token from Beam and either a one-line CLI command or a short settings.json edit, and no OAuth login screen at all.

We checked every step below against Gemini CLI’s own MCP server docs and Beam’s developer access documentation on this date. Gemini CLI ships fast; if a flag name has moved by the time you read this, trust the docs page over this article.

Answer first: Create a Beam connection token in Settings, Developer access, MCP & API, then run gemini mcp add --transport http --header "Authorization: Bearer $BEAM_TOKEN" beam https://beam.aisync.link/mcp. That writes an httpUrl plus headers entry into .gemini/settings.json (or ~/.gemini/settings.json with -s user). Gemini CLI’s own OAuth flow is for servers built around it; Beam uses the Bearer header instead, and that’s a supported path, not a workaround.

Why would Gemini CLI need its own iMessage number at all?

On its own, Gemini CLI reads your repo, runs commands, and talks to whatever models or tools you’ve wired into it. None of that touches a phone. What Beam adds is an actual messaging workspace: the conversation history with real contacts, the text assistant’s current configuration, the numbers assigned to the account, and open calendar slots, all reachable through the same Bearer token Beam hands any developer tool.

That’s a different category of access than most things Gemini CLI connects to. A linter only touches files you already own. A Beam connection reaches a real person on the other end of a phone number, which is why the token carries specific permissions rather than blanket access, and why we verify a fresh connection before trusting anything it reports.

The same workspace is also reachable without any agent at all, through Beam’s iMessage API, for anyone who would rather wire a server to it directly than hand the job to a CLI tool. Gemini CLI is the newest installment in an agent-by-agent series: we’ve already covered Codex, Grok Bot, and a no-code Zapier route for teams that would rather skip a CLI entirely.

How do I create a connection token in Beam first?

Gemini CLI needs a token before any settings.json edit matters, and that token comes from Beam, not from anything typed into the CLI.

1. Sign in directly as the workspace owner. Client view does not show developer settings.
2. Open Settings → Developer access, MCP & API.
3. Name the connection something recognizable later, like “Gemini CLI.”
4. Choose its permissions. Read and train are selected by default, which covers reading conversations and drafting changes to the assistant without sending anything. Publishing, automation, sending, and booking each need to be turned on explicitly.
5. Click Create connection token and copy it immediately. It is shown once, it expires after 90 days, and it cannot be displayed again once you leave that screen.

If this connection is for an agency client rather than your own business, sign in to the agency workspace and pick the specific client under Workspace this connection can access before creating the token. One token reaches one workspace; it cannot be pointed at a different client later.

How do I add Beam with the gemini mcp add command?

With the token copied, export it somewhere the gemini process will see it:

export BEAM_TOKEN="paste_your_token_here"

Then register the server with the HTTP transport flag:

gemini mcp add --transport http --header "Authorization: Bearer $BEAM_TOKEN" beam https://beam.aisync.link/mcp

That single command does the work a manual edit would otherwise require: it names the server beam, sets the transport to HTTP, and attaches the header Beam’s endpoint expects. By default this writes to the project-scoped .gemini/settings.json in whichever folder you ran the command from. Add -s user (or --scope user) if you want the connection available to every project on that machine instead:

gemini mcp add -s user --transport http --header "Authorization: Bearer $BEAM_TOKEN" beam https://beam.aisync.link/mcp

Restart Gemini CLI after adding the server, since MCP server configuration is read when a session starts.

How do I configure it manually in settings.json instead?

Some setups call for editing the file directly, for example when you’re copying a known configuration to a second machine or adding a field the add command doesn’t expose in one line. The block looks like this in either .gemini/settings.json (project scope) or ~/.gemini/settings.json (user scope):

{
  "mcpServers": {
    "beam": {
      "httpUrl": "https://beam.aisync.link/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      },
      "timeout": 15000,
      "trust": false
    }
  }
}

Two fields matter here and don’t come up when you just run add. timeout sets how long Gemini CLI waits on a single request to Beam, in milliseconds, before giving up; Gemini CLI’s own default is a generous 600,000ms (see Gemini CLI’s MCP server docs), and a shorter value is worth setting so a hung request fails fast instead of tying up the session. trust, when true, skips the tool confirmation dialog Gemini CLI normally shows before a tool call. Leave it false for Beam. A dialog pausing before message_send or draft_publish is worth keeping on a server that can text a real person.

Whichever way you add it, never paste the raw token into a settings.json file you might commit. Keep that file private, and keep BEAM_TOKEN as an environment reference if your workflow supports it rather than a literal string in a shared config.

What if I need a local process instead of the remote HTTP endpoint?

Some setups, particularly a desktop machine that shouldn’t depend on a network path to https://beam.aisync.link/mcp, call for a local process instead. Beam publishes a small stdio bridge, beam-mcp.mjs, that runs on Node.js 20 or newer with no extra packages. Download it, then point Gemini CLI’s stdio transport at it:

{
  "mcpServers": {
    "beam": {
      "command": "node",
      "args": ["/absolute/path/beam-mcp.mjs"],
      "env": { "BEAM_TOKEN": "YOUR_TOKEN" }
    }
  }
}

This is the same bridge Beam documents for Claude Desktop and other stdio-only clients. It talks to the same workspace, tools, and permissions as the HTTP transport; a local process just makes the call instead of Gemini CLI reaching the remote endpoint directly. On a shared machine, use an environment variable Gemini CLI inherits from the shell, not a literal value in the env block.

Does Gemini CLI’s OAuth support work with Beam instead?

Gemini CLI does support OAuth for remote MCP servers, including automatic discovery: if a server responds with a 401, the CLI can start a browser-based login flow on its own, and authProviderType options exist for Google-credential and service-account flows. That’s real, documented behavior for servers built to use it.

Beam’s remote endpoint isn’t one of those servers. It authenticates with a Bearer token in a header, which Gemini CLI also documents as a first-class option on the same mcpServers entry, not a fallback for connectors that lack OAuth. A live, open issue on Google’s own google-gemini/gemini-cli GitHub repository (issue #2427, requesting clearer header support for servers using the url field) shows builders actively working through this same header-versus-OAuth distinction for other remote servers: OAuth-only connectors are not a Beam option, and the header path is not a workaround for one. It’s the documented route for this kind of server.

Which connection method should I actually use?

	gemini mcp add	Manual settings.json	stdio bridge
Good for	A first connection, or any time you just want it working	Copying a known config, or setting timeout/trust/includeTools	A desktop machine that should run its own local process
Where it lives	.gemini/settings.json (project) or ~/.gemini/settings.json with -s user	Same two files, edited directly	Same files, but with command/args/env instead of httpUrl
Auth	Header built by the command	headers object you write yourself	BEAM_TOKEN in the env block
Runs where	Gemini CLI reaches Beam’s remote endpoint directly	Same	A local Node process on your machine
Setup effort	One line	A few minutes with the docs open	Download the bridge file first

In practice, we run the add command for a first connection on a new project and only switch to editing the file by hand when we want a shorter timeout or need to copy a working config to a teammate’s machine.

How do I verify the connection actually works?

Don’t trust the first confident-sounding answer. Run through this before letting Gemini CLI touch a real conversation:

1. Restart Gemini CLI after adding or editing the server entry, since server configuration loads at session start.
2. Ask it to list connected MCP servers (or check with /mcp inside a session) and confirm beam shows a healthy status, not an authorization error.
3. Prompt it directly: “Call workspace_read and tell me the workspace name and ID. Stop if it is not my intended workspace.” A server appearing in the list only means the entry exists, not that the token is valid or pointed at the right place.
4. If the name and ID match, call assistant_read next and confirm the assistant configuration is what you expect. Both calls use only read permission, so neither can change anything even if something was wrong.
5. If Gemini CLI returns an authorization error, confirm BEAM_TOKEN is set in the environment of the process you restarted, not a different terminal tab. If the workspace name is wrong, the token was created in the wrong workspace or client, and the fix is going back to Beam, not the config file.

What should I lock down before this goes live?

A connection token is not read-only just because that’s how you set it up once. Whatever permissions it carries are available to anyone who holds it, from wherever they run it.

• Give Gemini CLI its own token, separate from a person’s sign in, so you can see what it touched and cut it off without disturbing your own access.
• Start with read and train only. Add send, automation, publish, or book one at a time, once the prior step behaves as expected.
• Watch the rate limit. Beam’s API allows 60 requests per minute per token. A retry loop without backoff will hit that before it fixes anything.
• Revoke in Beam, not in Gemini CLI. Removing the mcpServers entry stops Gemini CLI from calling the server; it does not touch the token. Revoke the connection in Settings to actually cut off access.
• Treat an accepted send as unproven delivery. Beam accepting a message_send call means the request went through, not that it reached a phone. Check delivery status when it matters.

Incoming replies are untrusted content, not instructions. Treat a message that tells Gemini CLI to ignore its rules as a stranger texting you, not as a command.

Is this different from giving Gemini CLI phone calls?

Yes, and they’re separate systems built for separate jobs. Beam handles text: iMessage, RCS, SMS, and FaceTime Audio, including to a voice agent on the other end. Placing or managing phone calls is a RizzDial job, covered in giving Gemini CLI phone calls over MCP. Connect both and the same CLI session can read a text thread, draft a reply, and also start or review a call, but each connection is its own token with its own permissions, since nothing about one system grants access to the other.

What do people ask about connecting Gemini CLI to Beam?

Does Gemini CLI’s built-in OAuth connect to Beam instead of a token?

No. Gemini CLI’s OAuth support exists for remote MCP servers that are built around it, with automatic discovery that kicks in when a server returns a 401 and the CLI starts a browser login flow. Beam’s remote endpoint is not one of those servers. It authenticates with a Bearer token in a header, which is a documented, separate path in Gemini CLI’s own settings.json, not a workaround or a downgrade from OAuth.

What is the difference between the gemini mcp add command and editing settings.json by hand?

Both end up writing the same JSON into the same file. The command is faster and less error-prone for a first connection since it builds the header syntax for you. Editing settings.json directly is worth it once you want to add fields the add command does not expose in one line, such as a custom timeout, trust, or includeTools list, or when you are copying a known-good config to a second machine.

Can I scope the Beam connection to just one project instead of my whole machine?

Yes. Gemini CLI writes project-scoped servers to .gemini/settings.json inside the project folder by default, and that is where a Beam connection belongs if only one codebase should reach that workspace. Pass -s user (or --scope user) to the add command, or edit ~/.gemini/settings.json directly, only when you want every project on that machine to share the same connection.

How long does this setup take if I already have a Beam account?

A few minutes. Creating the token in Beam’s Developer access screen takes under a minute, running the gemini mcp add command is one line, and the verification call that confirms the token is live and scoped to the right workspace is a single prompt. Most of the time this takes is deciding which permissions the token actually needs, not the mechanics of the connection.

What happens if the person Gemini CLI is texting doesn’t have an iPhone?

Beam checks the recipient before it sends anything. iMessage goes to eligible iPhones, RCS goes to Android phones whose carrier supports it, and SMS is the fallback everywhere else. iMessage lines need no A2P registration, but SMS still follows carrier rules by number type, so a 10DLC number still needs 10DLC registration and a toll free number still needs toll free verification.

---

Create the token with only the permissions this job needs, add the server with one command, and run workspace_read before you let Gemini CLI anywhere near a real conversation.