MarginDeck MCP

简体中文 · MarginDeck · Support

A Node.js desktop extension that connects Claude Desktop to the installed MarginDeck Mac app. Ask about recorded product revenue, costs, estimated contribution profit, and cash runway. Financial reads require pairing approval in MarginDeck; proposed record changes require separate review before saving.

Status

Initial connector version: 0.1.0. This repository is prepared for a Claude Desktop extension directory application. It is not an Anthropic-approved or listed extension. Automated tests use synthetic data. A manual installation and pairing test of this Node.js package with Claude Desktop and the signed production app remains required before submitting the package; see the review checklist.

Related MCP server: Tiller Money MCP Server

Requirements

• macOS 14 or later. Windows and Linux are not supported.

• MarginDeck 1.6.0 or later, installed and running with MCP enabled in AI Connections. Obtain the app through the official website.

• Claude Desktop with desktop extension support. This is a local extension, not a remote connector for claude.ai or mobile.

• Claude Desktop supplies the Node.js runtime for Node extensions. Development and manual CLI use require Node.js 20 or later.

Installing this extension does not install or open MarginDeck, unlock Pro, or approve a connection. The app's normal entitlement and operation limits apply. This extension is separate from the binary extension exported by the app; install only one MarginDeck extension to avoid duplicate tools and pairing requests.

Build and install

git clone https://github.com/clot/margindeck-mcp.git
cd margindeck-mcp
npm ci --ignore-scripts
npm run check

The build writes dist/margindeck-0.1.0.mcpb. There are no third-party runtime dependencies. The pinned MCPB development dependency validates and packages the bundle; it is not shipped in the extension. Its transitive tmp dependency is overridden to 0.2.7 to address known temporary-path vulnerabilities.

1. Open MarginDeck and enable MCP in AI Connections.

2. In Claude Desktop, go to Settings → Extensions → Advanced settings → Install Extension…, then select the .mcpb file.

3. Set MarginDeck app location to the installed .app, normally /Applications/MarginDeck.app.

4. Ask Claude to call MarginDeck's get_status tool. Compare the pairing code and approve that client in MarginDeck.

5. Ask a financial question. Review proposed record changes in MarginDeck before confirming them.

Example prompts:

• “Summarize my recorded revenue and costs for this month.”

• “Compare the estimated contribution profit of my products.”

• “Explain my cash runway using the cash and recurring costs recorded in MarginDeck.”

Contribution profit is an operational estimate. Cash runway is a planning forecast based on recorded data, not a live bank balance or guarantee. The app computes these values; this connector does not invent or recalculate them.

How it works

Claude Desktop
  → Node.js extension (stdio JSON-RPC)
  → MarginDeck's authenticated loopback MCP endpoint
  → MarginDeck's authorized tools and in-app record review

Credentials: Node.js → signed MCPHeaders helper in the installed app
                    → MarginDeck's signed XPC service

The Node.js code implements bounded line framing, HTTP forwarding, protocol negotiation, response validation, timeouts, and credential refresh. It calls the app's native MCPHeaders headers helper only to obtain a short-lived credential. The connector does not launch the helper's stdio implementation or wrap a hidden binary MCP server.

The helper is an explicit native dependency supplied by the separately installed MarginDeck app. It is not redistributed here. App and helper signing identities are checked before invoking it. The user grants financial access in the app. A new credential starts a new pending pairing and does not inherit an expired or revoked approval.

The network destination is fixed to http://127.0.0.1:39983/mcp. There is no configurable remote endpoint, token setting, redirect following, proxy forwarding, telemetry, or direct database access. Credentials are kept in process memory and are never included in logs or the bundle. Data returned to Claude is shared with Claude; local storage does not mean AI responses stay on the Mac. See data handling.

Troubleshooting

To revoke access, use MarginDeck's AI Connections controls. To uninstall, remove the extension in Claude Desktop. Removing the extension does not delete your MarginDeck ledger.

Developer notes

npm test                  # Synthetic data only; no running app required
npm run validate          # Official MCPB manifest validation
npm run bundle            # Allowlisted, source-only .mcpb
node server/index.js --app /Applications/MarginDeck.app

The connector supports MarginDeck's JSON request/response MCP endpoint. It does not implement SSE, server-initiated requests, or in-flight cancellation. Requests are processed sequentially with pipe backpressure. Input is limited to 64 KiB per line, responses to 4 MiB, and each HTTP request to 20 seconds. HTTP 401/403 permits one credential refresh and initialization replay. Network failures, redirects and HTTP 5xx responses are not retried.

Report issues without including ledger data, tokens, or account credentials. For sensitive reports use the contact on MarginDeck's privacy page.

License

The source and documentation in this repository are MIT licensed. The separately distributed MarginDeck app and its native helper are not part of this repository and are not relicensed by this license. No app source, app binaries, or customer data are included.