|
1 | | -# Wiring ModelRisk MCP into Claude for Excel |
2 | | - |
3 | | -Claude for Excel runs inside an Office.js iframe sandboxed *inside* Excel itself. It can't spawn local subprocesses (the way Claude Desktop launches a stdio MCP server), so it talks to MCP servers over **HTTP** instead. ModelRisk MCP serves both stdio and HTTP transports. |
4 | | - |
5 | | -This is also where the architectural payoff is: Office.js can't reach Excel's COM surface or ModelRisk's ribbon. ModelRisk MCP, running outside the sandbox, can — which means Claude for Excel can do things via this server that it structurally can't do on its own. |
6 | | - |
7 | | -## Prerequisites |
8 | | - |
9 | | -- Excel 2019+ with ModelRisk loaded |
10 | | -- Claude for Excel installed (Microsoft AppSource → "Claude for Excel" by Anthropic) |
11 | | -- ModelRisk MCP installed: `pip install modelrisk-mcp` or the standalone `.exe` |
12 | | - |
13 | | -## 1. Start the server in HTTP mode |
14 | | - |
15 | | -Open a PowerShell window. Generate a token first — anything random and >=24 characters. PowerShell built-in: |
16 | | - |
17 | | -```powershell |
18 | | -$env:MODELRISK_MCP_TOKEN = [Guid]::NewGuid().ToString("N") + [Guid]::NewGuid().ToString("N") |
19 | | -$env:MODELRISK_MCP_TOKEN |
20 | | -``` |
21 | | - |
22 | | -Copy the printed token — you'll paste it into Claude for Excel in step 2. Then start the server: |
| 1 | +# Claude for Excel and ModelRisk MCP — the honest status |
| 2 | + |
| 3 | +> **TL;DR: Claude for Excel cannot currently reach this server. Use Claude |
| 4 | +> Desktop or Claude Code (local stdio) instead — `modelrisk-mcp install` |
| 5 | +> wires both.** This page replaces earlier instructions that described a |
| 6 | +> Settings → Connectors flow inside the add-in; those instructions were wrong |
| 7 | +> for shipping builds and are withdrawn (verified 2026-07 against a current |
| 8 | +> build, and independently confirmed by a field report). |
| 9 | +
|
| 10 | +## Why it can't work today |
| 11 | + |
| 12 | +Claude for Excel is an Office.js add-in running in a browser WebView. Its |
| 13 | +connector model has three properties that together rule out a local, |
| 14 | +Excel-driving MCP server: |
| 15 | + |
| 16 | +1. **No local Connectors panel.** The add-in's settings contain no "Add MCP |
| 17 | + server" entry. It resolves connectors from your **claude.ai account** |
| 18 | + connector list. |
| 19 | +2. **claude.ai custom connectors are remote.** The "Add custom connector" |
| 20 | + dialog takes a **remote MCP server URL** plus OAuth credentials, and those |
| 21 | + connectors are **fetched by Anthropic's infrastructure, not by your |
| 22 | + device**. A loopback URL (`http://127.0.0.1:8000/mcp`) is unreachable *by |
| 23 | + construction* — no configuration makes it work. The OAuth fields also |
| 24 | + don't match this server's bearer-token auth. |
| 25 | +3. **Local stdio servers never appear in the "Connectors" panel** on |
| 26 | + claude.ai or Claude Desktop. That's normal: the Connectors panel lists |
| 27 | + account-level remote connectors; local stdio servers are a separate, |
| 28 | + Desktop-only mechanism. Not seeing `modelrisk` there does **not** mean the |
| 29 | + install failed. |
| 30 | + |
| 31 | +The server side is fine — the HTTP transport handshakes correctly and |
| 32 | +enforces its bearer token (`401` without it). The limitation is entirely in |
| 33 | +how the client resolves connectors. |
| 34 | + |
| 35 | +## Do not tunnel around this |
| 36 | + |
| 37 | +The only technically-possible route to Claude for Excel today would be |
| 38 | +exposing the server through a public tunnel with OAuth in front. **We do not |
| 39 | +recommend or support this.** This server can write formulas into your |
| 40 | +workbooks, run simulations, and save files to disk. A publicly reachable |
| 41 | +instance guarded by a single bearer token is a materially different security |
| 42 | +posture from the loopback bind these docs are written around. If your |
| 43 | +organisation genuinely needs an in-Excel path, contact Vose — that is a |
| 44 | +product decision (a hosted connector with real auth), not a configuration |
| 45 | +setting. |
| 46 | + |
| 47 | +## What to use instead |
| 48 | + |
| 49 | +| Client | Transport | Status | |
| 50 | +|---|---|---| |
| 51 | +| **Claude Desktop** | local stdio | ✅ Supported, tested — `modelrisk-mcp install` | |
| 52 | +| **Claude Code** | local stdio | ✅ Supported, tested — `modelrisk-mcp install` (0.3.11+; earlier versions wrote the wrong config file) | |
| 53 | +| Cursor / Zed / other local MCP clients | local stdio | ✅ Works; configure manually | |
| 54 | +| An MCP client running on your own machine/LAN | `--transport=streamable-http` + bearer token | ✅ Works — keep the default loopback bind | |
| 55 | +| **Claude for Excel** | — | ❌ Not reachable by current builds | |
| 56 | + |
| 57 | +Everything this server does — building models, running simulations, reading |
| 58 | +results, charts, reports — works identically from Claude Desktop and Claude |
| 59 | +Code against the same Excel session you have open. Excel and ModelRisk are |
| 60 | +driven either way; only the chat window lives elsewhere. |
| 61 | + |
| 62 | +## HTTP transport (for clients that do run on your machine) |
23 | 63 |
|
24 | 64 | ```powershell |
25 | | -modelrisk-mcp --transport=streamable-http --port=8000 --token=$env:MODELRISK_MCP_TOKEN |
| 65 | +$env:MODELRISK_MCP_TOKEN = [Guid]::NewGuid().ToString("N") * 2 |
| 66 | +modelrisk-mcp --transport=streamable-http --host=127.0.0.1 --port=8000 --token=$env:MODELRISK_MCP_TOKEN |
26 | 67 | ``` |
27 | 68 |
|
28 | | -You should see: |
29 | | - |
30 | | -``` |
31 | | -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
32 | | -``` |
33 | | - |
34 | | -Leave the window open while you work. Closing it stops the server. |
35 | | - |
36 | | -> **Why a token?** The HTTP endpoint binds to `127.0.0.1` (loopback) by default, so only processes on your machine can reach it. But *any* process on your machine could otherwise hit it and drive Excel — including malicious ones. A bearer token shuts that down. If you bind to a non-loopback host, the token isn't optional. |
37 | | -
|
38 | | -## 2. Add the connector in Claude for Excel |
39 | | - |
40 | | -Open Excel, open Claude for Excel (the side-panel icon), then: |
41 | | - |
42 | | -1. Go to **Settings → Connectors** (or the equivalent in your current Claude for Excel build). |
43 | | -2. Click **Add MCP server**. |
44 | | -3. Fill in: |
45 | | - - **Name:** `modelrisk` (or anything you'll recognise) |
46 | | - - **URL:** `http://127.0.0.1:8000/mcp` |
47 | | - - **Authentication:** Bearer token |
48 | | - - **Token:** paste the token from step 1 |
49 | | -4. Save. |
50 | | - |
51 | | -Claude for Excel should report the connection as live and show the 40 ModelRisk tools. |
52 | | - |
53 | | -## 3. First conversation |
54 | | - |
55 | | -In Claude for Excel: |
56 | | - |
57 | | -> Summarise the active workbook's risk model — inputs, outputs, distributions. |
58 | | -
|
59 | | -Or jump straight in: |
60 | | - |
61 | | -> /build-risk-model |
62 | | -
|
63 | | -The same tool surface and same prompts as Claude Desktop. See [docs/demo-script.md](demo-script.md) for the headline workflow. |
64 | | - |
65 | | -## Lifecycle tips |
66 | | - |
67 | | -- **Token in another shell.** If you need to share the token with a second Claude for Excel session or paste it into a different config, save it to a file once and read it back. `Get-Clipboard` after the env-var line above also works. |
68 | | -- **Stopping the server.** `Ctrl+C` in the PowerShell window. The Claude for Excel connector will go red until you start it again. |
69 | | -- **Auto-start on boot.** Wrap the launch command in a Windows scheduled task running at logon, or a Start Menu shortcut. Keep the token out of source control. |
70 | | -- **Two-machine setup (advanced).** Bind to `0.0.0.0`, expose the chosen port through your firewall, and use a strong token. Watch the security model carefully — this server can write to your Excel. |
71 | | - |
72 | | -## Troubleshooting |
73 | | - |
74 | | -### "Connection refused" or "ERR_CONNECTION_RESET" |
75 | | - |
76 | | -The server isn't running, or it's bound to a port Claude for Excel can't reach. Check the PowerShell window — uvicorn prints `Uvicorn running on http://127.0.0.1:8000` when it's healthy. |
77 | | - |
78 | | -### 401 Unauthorised |
79 | | - |
80 | | -The token Claude for Excel is sending doesn't match the one the server expects. Re-paste it. Tokens are case-sensitive. |
81 | | - |
82 | | -### Tools listed but every call hangs |
83 | | - |
84 | | -The server is running but can't reach Excel. Confirm Excel is open and ModelRisk is loaded. Try the standalone `modelrisk-mcp --transport=stdio` with Claude Desktop first — that's a simpler topology to debug. |
85 | | - |
86 | | -### Concurrent-writer errors |
87 | | - |
88 | | -If Claude Desktop is running the same server over stdio at the same time, the writer mutex will reject one of them. Pick one client per session, or run the HTTP server with a different mutex name (advanced — see `src/modelrisk_mcp/safety.py`). |
89 | | - |
90 | | -### "version": "1.27.1" in serverInfo |
91 | | - |
92 | | -That's the FastMCP library version FastMCP currently reports, not our package version. Cosmetic, doesn't affect behaviour. The actual server is identifiable as `"name": "modelrisk-mcp"`. |
93 | | - |
94 | | -## Security model — important |
95 | | - |
96 | | -ModelRisk MCP over HTTP is a **local-only, single-user** integration in its default configuration. The defaults: |
| 69 | +- `POST /mcp` with `Authorization: Bearer <token>` → MCP initialize handshake. |
| 70 | +- No token → `401`. |
| 71 | +- Keep `--host=127.0.0.1` unless you fully understand the exposure of |
| 72 | + `0.0.0.0` on your network. |
| 73 | +- Add `--read-only` for a first session against a model you care about |
| 74 | + (0.3.11+): reading and analysis work; writes, simulations and saves are |
| 75 | + refused with a clear error. |
97 | 76 |
|
98 | | -- Loopback bind (`127.0.0.1`) — only your own machine |
99 | | -- Bearer token required if you change the bind to a non-loopback host |
100 | | -- No outbound network calls — the server doesn't phone home |
101 | | -- All writes still default to `dry_run=True`; the writer mutex still serialises commits; the audit log still records every change |
| 77 | +## If Anthropic's connector model changes |
102 | 78 |
|
103 | | -Do **not** expose this server to the public internet. The MCP tool surface includes `replace_constant_with_distribution`, `run_simulation`, and `set_named_range` — anyone who can reach the endpoint with a valid token can drive your Excel. Treat the token like an API key. |
| 79 | +If a future Claude for Excel build adds local MCP support or a |
| 80 | +device-fetched connector mode, this page will be updated and the client |
| 81 | +re-tested before instructions are published. Watch the CHANGELOG. |
0 commit comments