Use your book from other AI apps
Open Net Worth is itself an MCP server, so any AI app that speaks MCP — Claude Desktop, Claude Code, Cursor, VS Code (Copilot), ChatGPT, Cline, Continue — can connect to your book and use the same tools Lucius has: look up balances, search transactions, add and categorize them, check the budget, and so on.
This is the opposite direction from External MCP servers, where Lucius uses someone else’s server.
Before you start
- Open Net Worth must be running whenever the other app uses it (for the desktop app, it must be open or running in the background).
- Your API token is what lets the other app in. One exists already — you don’t create it. It lives in Settings → Security → API token, and Copy config (below) puts it into the config for you.
Set up Claude Desktop, Cursor, VS Code, Cline or Continue
These apps run on your computer, so they connect through a small bridge program that the app starts for you.
-
In Open Net Worth, open Settings → MCP.
-
Under Connect from…, click your app: Claude Desktop, Cursor, VS Code (Copilot) or Cline / Continue / other.
-
If you run Open Net Worth as a server rather than the desktop app, pick how it runs: Installed (onw), Running from source, or Docker or another computer (see Docker, or an AI app on another computer). With Docker, Settings picks the last one for you.
-
Click Copy config. The copy contains your real API token (the screen shows a placeholder,
ONW_API_TOKEN_PASTED_ON_COPY, so the token never appears on the page). -
Paste it where the hint on screen says:
App Where to paste Claude Desktop Settings → Developer → Edit Config opens claude_desktop_config.json. Paste it in (merge it into"mcpServers"if you already have other servers), save, and restart Claude Desktop.Cursor ~/.cursor/mcp.json(all projects) or.cursor/mcp.json(one project).VS Code (Copilot) .vscode/mcp.json(workspace) or your usermcp.json. VS Code uses"servers", not"mcpServers".Cline / Continue / other The app’s MCP settings file, in its mcpServerssection.For Cursor, VS Code and “other”, the copied text holds two alternatives separated by
// — or —lines. Paste only one of them (the stdio one, for an app on the same computer) — the comment lines and the second block would make the file invalid. -
Check it works: in the AI app, ask “Using open-net-worth, what’s my net worth?” It should answer with your figure. In Claude Desktop, the server also appears under its connectors/tools list.
A Claude Desktop config looks like this (server installed with onw):
{ "mcpServers": { "open-net-worth": { "command": "/Users/you/.local/bin/onw", "args": ["mcp"], "env": { "ONW_BASE_URL": "http://127.0.0.1:8080", "ONW_API_TOKEN": "your-api-token" } } }}What the command is depends on how you installed Open Net Worth — Copy config fills in the
right one:
| Install | What the config runs |
|---|---|
| Desktop app | The Python bundled inside the app, with -m backend.cli mcp. Instead of an address, the config names your book folder (ONW_ROOT), because the desktop app picks a new address each time it starts and the bridge finds the current one there. If you move the app or switch book folders, copy the config again. |
Installed (onw) | The onw command, with mcp. Settings fills in its full path when it can, because apps like Claude Desktop don’t search your shell’s PATH. |
| Running from source | python3 -m backend.mcp.stdio_bridge, run in your checkout folder. See the troubleshooting note below if your app can’t start it. |
| Docker or another computer | onw mcp, installed on the computer where the AI app runs, with the address of your Open Net Worth. See below. |
Docker, or an AI app on another computer
When Open Net Worth runs in Docker, or on another computer (a home server, a NAS), the AI app can’t start anything from it: the programs inside the container or on the server don’t exist on the computer where the AI app runs. So that computer gets its own copy of the bridge:
-
On the computer running the AI app, install the bridge:
Terminal window uv tool install open-net-worthThis doesn’t start a second Open Net Worth there.
onw mcponly passes each message from the AI app to your instance’s address and hands the answer back. -
On that same computer, open Open Net Worth in the browser, go to Settings → MCP, choose Docker or another computer and click Copy config. Copying it there puts in the address that computer reaches your instance at.
-
Paste it into the AI app as in the steps above.
You don’t need to update the bridge when you update Open Net Worth. It doesn’t contain any Open Net Worth tools: each time the AI app connects, it asks your instance for the tool list, so new tools appear on their own. It depends only on the MCP standard itself.
If you’d rather install nothing from Open Net Worth on that computer, the generic mcp-remote
bridge does the same job. It needs Node.js. Turn on Use npx instead under Docker or another
computer and Copy config gives you this, with your token filled in:
{ "mcpServers": { "open-net-worth": { "command": "npx", "args": ["-y", "mcp-remote", "http://your-server:8080/mcp", "--allow-http", "--header", "Authorization:${ONW_AUTH}"], "env": { "ONW_AUTH": "Bearer your-api-token" } } }}--allow-http is only needed for an http:// address. The token sits in env because some
apps break an argument that contains a space.
Set up Claude Code
Claude Code has no tab of its own in Settings → MCP, but it takes the same configuration:
-
In Settings → MCP, choose Claude Desktop and click Copy config.
-
Take the part inside
"open-net-worth": { … }and add it from a terminal:Terminal window claude mcp add-json open-net-worth '{"command":"/Users/you/.local/bin/onw","args":["mcp"],"env":{"ONW_BASE_URL":"http://127.0.0.1:8080","ONW_API_TOKEN":"your-api-token"}}'Add
--scope userto make it available in every project. -
Check with
claude mcp list—open-net-worthshould show as connected — then ask Claude Code about your book.
If Open Net Worth runs as a server (not the desktop app), you can instead connect over HTTP:
claude mcp add --transport http open-net-worth http://127.0.0.1:8080/mcp \ --header "Authorization: Bearer your-api-token"Set up ChatGPT or another hosted app
Hosted apps run on their provider’s servers, so they can’t start a program on your computer or
reach localhost. They connect over HTTP to <your address>/mcp with the token as a Bearer
header.
- Make your instance reachable at a public HTTPS address first — see Exposing beyond localhost. (This needs a server install; the desktop app only accepts connections from its own computer.)
- Open the app through that public address, go to Settings → MCP, choose ChatGPT or Generic HTTP / remote, and click Copy config.
- ChatGPT: Settings → Connectors (with Developer mode on) → Add custom connector, and
enter the MCP server URL (
https://your-address/mcp) and the Bearer token from the copied text. Other apps: use the copiedurlandAuthorization: Bearer …header.
What a connected app can do
An app holding your API token acts as you: it can read your whole book and make changes.
- No approval cards. When Lucius wants to make a change that needs your approval, he shows you a card first. Other apps don’t get those cards: a tool set to Needs approval runs straight away when another app calls it. Only tools set to Blocked in Settings → Permissions are refused. If you’d rather an app couldn’t change something, block that tool.
- Changes are recorded. Each change another app makes is logged and saved as a checkpoint, so you can undo it like one Lucius made. Things that leave the app — an email or message sent, code run — can’t be undone.
- One token for every app. Rotating it in Settings → Security → API token → Rotate disconnects every app configured with the old one, and every installed iPhone Shortcut, at once. There’s no confirmation step. Afterwards, Copy config again and paste the new one into each app.
Troubleshooting
Claude Desktop says “Server disconnected” / the tools don’t appear
- Open Net Worth isn’t running — start it, then restart Claude Desktop.
- The app can’t find
onw. Replace"command"with the full path printed bywhich onw(Windows:where onw). - The log says
Failed to spawn process: No such file or directoryand Open Net Worth runs in Docker or on another computer:onwisn’t installed where the AI app runs. See Docker, or an AI app on another computer. - The JSON is invalid — check you pasted only one block and didn’t leave
//comment lines in.
“cannot reach Open Net Worth MCP server at …” — the bridge started but Open Net Worth isn’t
running at that address. Start it. With a server install, check ONW_BASE_URL matches the
address you open in your browser.
It worked, then stopped
- You rotated the API token, or set a password for the first time (setting the first password also replaces the token). Copy the config again.
- Desktop app: a config containing a
127.0.0.1:<port>address goes stale when the app restarts. Copy the config from inside the desktop app so it usesONW_ROOTinstead.
“Running from source” fails with No module named … — the app started your system
python3, not the checkout’s environment. Change "command" to the checkout’s own onw,
/path/to/open-net-worth/.venv/bin/onw (created by make setup), set "args" to ["mcp"], and
remove "cwd".
“authentication required” (401) — the token in the config is wrong or old. Copy the config again.
ChatGPT can’t connect — it can’t reach localhost or a home-network address; it needs a
public HTTPS address (see step 1 above).
Related pages
- Exposing beyond localhost — a public address for hosted apps
- Permissions — blocking tools you don’t want changed
- External MCP servers — the other direction
- Security and privacy
Guides and comparisons
Longer write-ups on the Open Net Worth blog:
- Personal Finance MCP Server: Use Your Ledger from Claude: a walkthrough of the MCP server with Claude
- An Open-Source Claude Personal Finance Alternative: Claude’s own personal finance features next to a self-hosted ledger