Excel AI Bridge — alpha

Connect a Claude client to the bridge

Tutorial 1 put the add-in in Excel, and the ribbon said no AI was connected. This one fixes that: by the end, a Claude client will be able to read the workbook that is open in front of you, and the ribbon will say so.

The bridge speaks MCP, which is simply a way for a Claude app to call tools that run on this machine — here, tools that read and change the workbook Excel already has open. Nothing is uploaded; Claude asks, the bridge reads the live book, and answers.

Prerequisites

for that downloaded script), AIBridge.xlam is in Excel's XLSTART folder and the AI Bridge tab appears on the ribbon.

so an unsaved Book1 has nothing to bind to. These pages use TutorialDemo.xlsx, which ships in this folder of the release zip.

install.cmd put on this machine.

How Claude reaches the bridge

The bridge dials out to a hosted broker, prints one URL, and you paste that URL into claude.ai — no tunnel, no DNS, no cloud console. The Claude desktop app has the same Settings → Connectors page as claude.ai and the same list of connectors, so a connector added in one is there in the other. Any other client — a script, another AI app — uses this bridge's client token instead, described below.

Connect claude.ai through the hosted broker

With the add-in installed, open a saved workbook and press Connect AI. If no bridge is running, the ribbon starts it — bridgehost.exe --broker --connect-ui, from the folder install.cmd installed it to. The tray icon shows it running, then the add-in attaches as today. The invite is already in invite.json at the zip root, so you do not type a code.

You can also start it by hand from that folder, %LOCALAPPDATA%\ExcelAIBridge\releases\<version>: 

bridgehost.exe --broker

Started by hand it shows no progress window. The connector URL is still behind the ribbon's Show password button. The connector URL line it writes to %LOCALAPPDATA%\ExcelAIBridge\bridge.log names the id only by a short hash.

Connecting saved and locked this workbook, so Excel's undo list starts again from here. The bridge puts a password on the file while it is connected and saves it, and Excel clears its undo list on every save. The first time a workbook is connected, the Status line says Locked: undo starts here; rest the pointer on it for the whole sentence. When private columns wait for your choice because the AI Bridge window cannot show it, the Status line says that first, and this sentence follows in its tip. With EXCEL_BRIDGE_LOCK_ON_BIND=0 nothing is saved and nothing is said.

If you start by hand without invite.json, put the invite in the environment (invite.json wins whenever it is there, so this is the fallback — and a bridge that registers from the environment says (env override) while it does): 

set EXCEL_BRIDGE_INVITE=the-code-you-were-given

The bridge registers itself with the broker once, and stores the identity it gets back — DPAPI-protected, so it is readable only by this Windows account on this machine — in %LOCALAPPDATA%\ExcelAIBridge\broker.json. Later starts read that file and need no invite code at all. On the way up it prints four lines on stderr: 

AI Bridge: connector URL .../id-<hash>/mcp
AI Bridge: Google redirect to register: https://bridge.ram.sh/auth/callback
AI Bridge: accounts allowed: y***@example.com
AI Bridge: linked to https://bridge.ram.sh

<id> is this bridge's own 32-hex id, minted at registration and the same on every later start. These lines reach bridge.log, so they name the id only by <hash>, the first 8 hex characters of the id's SHA-256, and keep only the first letter of each address; the whole connector URL is on the page the bridge opens (below) and on its account page. The Google redirect is fixed at https://bridge.ram.sh/auth/callback and is already registered in the shared OAuth app, so there is nothing for you to add in a Google console.

Then add it in claude.ai:

  1. Settings → Connectors → Add custom connector.
  2. Paste the connector URL from the page the bridge opened (it has a Copy connector URL button; the same page is behind the ribbon's Show password button) —

https://bridge.ram.sh/<id>/mcp.

  1. Press Connect.
  2. Approve the bridge's consent page when it appears. It asks you to look at the

address it shows before you approve. The callback address is where the bridge sends Claude's key; if it is not claude.ai, someone else is asking.

  1. Sign in with Google, using an address that is on this bridge's list.

On a bridge installed from an invite, the list is the one Google address that invite was made for, and only that address signs in. Nothing on this computer adds or removes an account. To let another person in, ask whoever gave you the invite for an invite in that person's name. An invite that carries no address, and a bridge started by hand from EXCEL_BRIDGE_INVITE with no invite.json beside it, take the service's shared sign-in list, the same one for every such bridge rather than one picked for yours, and only when the service sends none does the bridge read %LOCALAPPDATA%\ExcelAIBridge\allowed.json on that machine - which no page writes. An invite.json that cannot be read, or that has gone from a bridge that registered from it, lets nobody in: put it back, or ask for a new invite.

Signing in with any other Google account does not half-work: the bridge turns it away, because that address is not on this bridge's list, and claude.ai shows the connector as connected with no tools. The owner's Account page (the ribbon's Account button) shows the seat - its Google address, plan and state - and the broker's verdict on the last sign-in: allowed by your seat, or refused because that account is not the seat's, with the time in UTC; the verdict names no address. An empty list is not an open door: nobody gets in until the seat or a list names someone.

Nothing outside this machine can reach a port on it. The bridge's own listeners answer on 127.0.0.1 only, for this machine alone. It opens an outbound WebSocket to the broker and keeps it, so claude.ai's request arrives down a connection you dialled — which is why there is no tunnel to run, no port to forward and no firewall rule to write. The broker only relays bytes between claude.ai and your bridge: the Google sign-in is checked against your allowlist, the workbook and the audit log stay on this machine, and the identity in broker.json never leaves it.

Other clients: the client token

claude.ai signs in with Google. A client that cannot — a script, another AI app — presents this bridge's client token instead, and is then served exactly like a signed-in claude.ai request: the same three tools, the same refusals, the same privacy rules.

Where to find it. The page behind the ribbon's Show password button — the same page that carries the connector URL — has a Client token card. If this bridge has none, the card has a Create client token button; press it and the value appears with a Copy client token button. That page is the only place the value is ever shown: it is not in the audit, the log, the task pane or any reply, and the account page shows only that a token exists.

> Anyone holding this token can do in this workbook what you allow the AI to do; > treat it like the workbook's password.

Using it. Send it as the bearer token to the same connector URL claude.ai uses: 

Authorization: Bearer <the client token>

Send a real User-Agent. Cloudflare's bot rule in front of bridge.ram.sh answers 403 (error 1010) to a request whose User-Agent is a library default — Python's urllib is the one that caught us — and that refusal happens before the request ever reaches the bridge. Set a normal browser-style User-Agent on the client and the call goes through.

Rotate and Revoke. The bridge's Account page lists Client token: active since <date> or Client token: none. Rotate makes a new token and stops the old one at once; Revoke deletes it and this bridge accepts none until you make another. Either way the next request carrying the old token gets the ordinary 401, and the journal keeps one line saying what you did — never the token itself.

Point it at a workbook, and prove the link

The steps below follow a run in claude.ai against TutorialDemo.xlsx. The Claude desktop app looks the same — same questions, same replies.

  1. Ask Claude for anything that needs the workbook, and it stops to ask

permission first. Here the request was *"Bind the workbook at C:\Users\you\Documents\TutorialDemo.xlsx"*, and Claude will not use the bridge until you say so. Choose Always allow: it grants that tool from now on, so Claude stops asking for it and the work runs without a dialog in the way. The other button grants the single call in front of you and nothing more, and the dialog comes back the next time. The dialog appears once per new tool, so expect a handful of them early on and almost none later.

  1. Claude binds the workbook and answers with what it bound: the full path,

the transport, the port, and whether the file was locked on disk. Give it the full path, always. The bridge binds by nothing else — not a file name, not "the workbook I have open" — and a path that is not currently open in Excel is refused rather than guessed at. That refusal is the whole point: with two revisions of the same budget open, "the active workbook" is whichever one you happened to click last, and a write can land silently in the wrong copy. A full path cannot be ambiguous.

  1. Switch to Excel. The AI Bridge tab now reads AI connected with a green,

smiling robot, and the tab strip itself says AI Bridge - connected. That light is not the button remembering it was pressed: the bridge republishes its state every few seconds and the ribbon only reports what it reads, so a bridge that dies goes dark on its own. Two neighbouring states are worth learning now. Waiting for AI, amber, means this workbook was offered but nothing has picked it up yet. Connect here, red, means a bridge is live but holding a different workbook — press it to move the binding to this one.

  1. Ask "Which workbooks are you holding right now?". Claude answers with a

name, a full path and a session id for each one. Binding is additive: binding a second workbook does not replace the first, it adds to it, and once more than one workbook is bound every other request has to say which one it means. This is the question to ask whenever you are unsure what Claude is actually looking at.

  1. Back in Excel, select a few cells — here the headcount column, Budget!C3:C7.

Do not tell Claude which cells you picked. The point of the next step is that it can find out for itself.

  1. Ask "What cells do I have selected in Excel right now?". Claude comes

back with the address you just dragged over and the values inside it. This is the clearest proof the link is live in both directions: nothing about that selection was ever typed into the chat, so the only way Claude can know it is by reading the workbook you are sitting in front of, at the moment you asked.

  1. Finish with a plain read: "Read Budget!A2:E7 and show me the rows."

Claude shows the values, the formulas behind them, and — if any of those cells were marked private — the addresses whose values were replaced by [redacted], with one sentence saying so. The contents of a private cell never leave the machine; only the fact that something was hidden does. Every one of these calls is appended to %LOCALAPPDATA%\ExcelAIBridge\audit\<workbook-key>.jsonl with the caller's identity, so you can go back later and see exactly what was read.

> Who can do any of this? Only the Google accounts written down in advance. > Signing in with Google proves you are somebody; it does not prove you are > the person this bridge belongs to. So the door opens only for addresses that > were listed before anyone knocked - on a bridge installed from an invite, the > one address that invite was made for. Everyone else is turned away at the > door, even holding the same link. Sign out from the tray or that page and the door closes again: > the next request from claude.ai is refused and Claude asks to reconnect.

When it does not work

and nothing has answered it. Either no bridge is running, or the one that is running is bound to a different file. Press Status on the AI Bridge tab for the state in words, and read the bridge's own log, %LOCALAPPDATA%\ExcelAIBridge\bridge.log.

workbook. This is the wrong-workbook case the whole project exists to prevent, which is why it is the loud one. Press the button, or ask Claude to bind this file by its full path.

read the bridge's log, %LOCALAPPDATA%\ExcelAIBridge\bridge.log, for AI Bridge: linked to https://bridge.ram.sh. If it says `broker link down`, the bridge is already retrying by itself and will link again on its own. A line that says broker link dropped at ... and relinked at ... is a blip that healed by itself: under 10 seconds, nothing is shown in the tray or the ribbon for one. If it says close 4401, the service no longer knows this bridge's token: the bridge has already set broker.json aside, and the next Connect AI registers it again with the same invite. Compare the whole connector URL on the Show password page with the one in claude.ai's connector settings (the id-<hash> in the connector URL line also changes when the id does): if the service gave the bridge a new id, the URL changed and the connector needs the new one from the Show password page. If it says This bridge's invite is no longer valid; ask for a new one., the invite itself was revoked: put the new code in invite.json if there is one (it wins), otherwise in EXCEL_BRIDGE_INVITE, and connect again.

After the bridge gains or loses a tool, disconnect and reconnect the connector in Settings so that it fetches the list again.

this bridge's list. Signing in with Google proves you are somebody; the list is what makes this your bridge rather than everyone's. On a bridge installed from an invite, the list is the address that invite was made for: ask whoever gave you the invite for one in that person's name. Account on the AI Bridge tab (or Allowed accounts... in the tray menu) shows the seat and the broker's verdict on the last sign-in, so you can see that the refusal was that one; it adds no address. The same page shows who is signed in, switches account and signs out.

The account you signed in with has an AI Bridge of its own, but the connector in your AI client names another one that belongs to someone else, usually a connector kept from an older install. To connect your own, remove that connector and add it again with the connector URL your bridge shows now (behind the ribbon's Show password button). If the connector is the one you meant - you have two accounts and picked the wrong one when signing in - keep it: start the connection again and sign in with the account that AI Bridge was set up for.

fresh bridge holds nothing and refuses to guess. Every tool refuses until something binds a workbook: asking Claude to bind one by its full path, or the ribbon's connect button.

Next: Work back and forth — reading, writing, formatting, undo, and watching the privacy guard refuse.