mcp-for-lunchflow

Unofficial MCP server for Lunch Flow. Not affiliated with, endorsed by, or supported by Lunch Flow.

A small, read-only Model Context Protocol server that lets an AI agent read your bank accounts, transactions and balances through the Lunch Flow Personal API, using your own API key. It was built for Hermes Agent, but works with any MCP client that runs stdio servers.

• One file of code (server.mjs); dependencies are only the official MCP SDK and zod, pinned exactly.

• Read-only: it can only call GET endpoints. It cannot move money or change anything.

• Published from GitHub Actions with npm provenance, so every release from 1.2.0 onwards is traceable to the commit it was built from.

Tools

Related MCP server: LunchMoney MCP Server

Requirements

• Node.js 22 or newer

• A Lunch Flow account with at least one connected bank

• A Lunch Flow API key: in Lunch Flow, go to Destinations → Add Destination → REST API and copy the key

Install

Install a specific version globally. --ignore-scripts is a good habit for any package you install as root:

npm install -g @faberjustin/mcp-for-lunchflow@1.2.0 --ignore-scripts

Dependencies are locked with npm-shrinkwrap.json, so you get exactly the versions that were tested.

To check the release was built by this repository's GitHub Actions workflow, look at the Provenance section on the package's npm page, or verify it from the command line. (npm audit signatures does not work on global installs, so this uses a throwaway folder.)

mkdir -p /tmp/verify && cd /tmp/verify && npm init -y >/dev/null
npm install --ignore-scripts @faberjustin/mcp-for-lunchflow@1.2.0
npm audit signatures

Configure Hermes Agent

1. Store the key in ~/.hermes/.env, creating the file as private first:

   [ -f ~/.hermes/.env ] || install -m 600 /dev/null ~/.hermes/.env
   chmod 600 ~/.hermes/.env
   echo 'LUNCHFLOW_API_KEY=your-key-here' >> ~/.hermes/.env

2. Print the config block with the right absolute paths for your machine:

   cat <<EOF
   
     lunchflow:
       command: "$(command -v node)"
       args: ["$(npm root -g)/@faberjustin/mcp-for-lunchflow/server.mjs"]
       env:
         LUNCHFLOW_API_KEY: "\${LUNCHFLOW_API_KEY}"
       connect_timeout: 30
   EOF

3. Paste it under mcp_servers: in ~/.hermes/config.yaml, then run /reload-mcp and ask: "list my Lunch Flow accounts".

Use absolute paths. Hermes may not use your shell's PATH, and may run a bare node or npx with a different Node.js than the one you installed.

Configure other MCP clients

Any client that runs stdio servers can use the same command and environment, for example:

{
  "mcpServers": {
    "lunchflow": {
      "command": "mcp-for-lunchflow",
      "env": { "LUNCHFLOW_API_KEY": "your-key-here" }
    }
  }
}

That needs both node and npm's global bin folder on the client's PATH, which desktop apps (especially on macOS) often don't have. If the server doesn't start, use absolute paths instead: "command": "/absolute/path/to/node" and "args": ["/absolute/path/to/server.mjs"]. command -v node and npm root -g show the paths.

If your client supports remote MCP servers with OAuth, you may prefer Lunch Flow's own hosted server instead; see their MCP guide.

Configuration

The server refuses to start if NODE_OPTIONS is set, because runtime flags could weaken it. Some setups set it globally, for example --use-openssl-ca behind a corporate proxy. If yours does, unset it for this server only: MCP clients pass only the environment you configure, plus a few basics.

Security

What the server does:

• Your key stays private. It is sent only in the x-api-key header to the configured API host, and never logged or returned to the model.

• The connection can't be weakened. TLS is required. The server refuses to start with an invalid key, credentials in the URL, NODE_TLS_REJECT_UNAUTHORIZED=0, or NODE_OPTIONS set.

• Redirects are refused, so the key is never forwarded to another host.

• Requests are bounded. Each one has a hard 20-second deadline and a 5 MB response cap.

• Output is cleaned. Only allowlisted fields are returned. Text from banks and third parties (merchant names, descriptions, account names) is length-capped and stripped of control, invisible and text-direction characters.

• Tool input is strict. Account ids, dates and limits are validated, and unknown arguments are rejected.

What it cannot do for you:

• Transaction text is written by other people. Anyone who pays you, or any merchant, can put text into your transactions. An AI agent might treat that text as instructions. The server cleans and caps it, but it cannot rule this out. Don't let an agent that reads your bank data also act without your approval. In particular, avoid running it as root with an unrestricted shell.

• An agent with a shell can read the key from ~/.hermes/.env or the process environment. The Lunch Flow key is read-only, but it can see all your bank data. Rotate it if you suspect it was exposed.

To report a vulnerability, see SECURITY.md.

Development

npm ci --ignore-scripts
npm test

The tests start the real server over stdio against a local mock of the Lunch Flow API.

Disclaimer

This is an independent, unofficial project, provided as-is and maintained on a best-effort basis. "Lunch Flow" is used only to describe what this software works with. All trademarks belong to their respective owners.

License

MIT © 2026 Justin Faber