Beeswax Shares MCP Server

A standalone Model Context Protocol server for Beeswax Shares, the SMSF (Australian self-managed super fund) portfolio app. It is a thin client over the app's JSON API (/api/v1), letting Claude (Desktop or Code) read portfolio data, recall transaction history, upload statements, and propose new ledger records for human review.

Claude connects to it over stdio. All money amounts are AUD unless stated otherwise.

How writes work (important)

The record_trade and record_income tools never write directly to the ledger. They create proposed transactions that land in the app's Review Queue, where a human approves or rejects them before anything touches the books. Proposals accept an external_ref idempotency key, so repeated imports of the same source (e.g. the same email) will not create duplicates.

record_cost and update_price write low-risk records (holding costs and price observations) directly. create_holding creates a new security record directly — the buy itself should still go through record_trade.

Tools

List tools include a pagination object (total_count, page, per_page, total_pages) in their results. page/per_page query params are supported, per_page max 100.

Creating an API token

1. Sign in to the Beeswax Shares app.
2. Go to Account → API Access.
3. Create a token with the scopes you need (read scopes for browsing; proposals:write, documents:write, costs:write, prices:write, holdings:write for the write tools).
4. Copy the token — it is shown once.

Build

Requires Node 18+.

cd mcp-server
npm install
npm run build

This compiles TypeScript to dist/index.js.

Distribute as a Desktop Extension (.mcpb)

The easiest way to give this to other people is to package it as a Desktop Extension — a single .mcpb file they open in Claude Desktop. Claude Desktop runs it with its own bundled Node (users need nothing installed) and prompts each user for their own API token, stored securely in the OS keychain. Each token scopes access to that user's own funds, so the same bundle works for everyone.

Build the bundle (maintainer)

cd mcp-server
npm install            # all deps (incl. TypeScript, for the build)
npm run build          # compile to dist/index.js
npm prune --omit=dev   # drop dev deps so they don't ship in the bundle
npx @anthropic-ai/mcpb pack . beeswax-shares.mcpb

This produces beeswax-shares.mcpb (~3 MB). The bundle's metadata and the user-facing config form live in manifest.json; mcpb pack validates it. Distribute the .mcpb via a GitHub Release, a download link, or email — it is a build artifact and is git-ignored, not committed.

Optional: npx @anthropic-ai/mcpb sign adds a code signature so users don't see an "unverified publisher" prompt on install. Unsigned bundles still install fine, with a one-time confirmation.

Install (end user)

1. Download beeswax-shares.mcpb.
2. Open it with Claude Desktop (double-click) — an install dialog appears.
3. When prompted, paste your API token (create one at Account → API Access in Beeswax Shares — it is shown only once). Leave Server URL as the default unless you run your own instance.
4. Done — the Beeswax Shares tools are now available in Claude.

Configuration (manual / developer setup)

For local development or non-Desktop clients, configure the two environment variables directly. End users should prefer the .mcpb Desktop Extension above.

Two environment variables:

If your default node is older than 18 (check node --version), use the absolute path to a Node 18+ binary in the configs below, e.g. ~/.nvm/versions/node/v20.18.0/bin/node.

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "beeswax-shares": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "BEESWAX_URL": "https://alpha.beeswaxapp.com",
        "BEESWAX_API_TOKEN": "your-token-here"
      }
    }
  }
}

Claude Code

claude mcp add beeswax-shares \
  -e BEESWAX_URL=https://alpha.beeswaxapp.com \
  -e BEESWAX_API_TOKEN=your-token-here \
  -- node /path/to/mcp-server/dist/index.js

Security note

The API token grants access to the fund's financial records — treat it like a password: keep it out of source control, scope it minimally, and revoke it from Account → API Access if it leaks. As a safeguard, the record_trade / record_income tools only ever create proposals pending human approval in the app's Review Queue; they cannot post to the ledger directly. All API writes are audit-logged server-side.