Banana Accounting MCP Server

A Model Context Protocol (MCP) server, written in TypeScript, that exposes the Banana Accounting Plus Integrated Web Server API V2 to LLMs. Point your MCP-capable client (Claude Desktop, Cursor, etc.) at this server and the model can read your accounts, balances, journals, reports and VAT data — and create new accounting files — directly from your locally running Banana Accounting instance.

Every documented endpoint from the API V2 Get Data and Send Data references is exposed as a dedicated tool. See the full tool reference below.

The Banana Integrated Web Server is read-only for existing files — for security it cannot modify an open accounting file. The only write operation it offers is creating a new file (which Banana opens for you to review). This server mirrors that capability faithfully.

Requirements

• Node.js >= 18 (uses the built-in global fetch).

• Banana Accounting Plus 10.1.7+ with the Advanced plan (the Web Server feature requires it).

• The Integrated Web Server enabled and reachable (see below).

Enabling the Banana Web Server

1. In Banana Accounting Plus: Tools → Program Options → General, check Start Web Server (on macOS also Start Web Server with SSL — see the macOS setup guide).

2. Edit httpconfig.ini and set an accessToken under the [Banana] section, and set accessControlAllowOrigin=* (see Web Server security). To locate the file: Tools → Program Options → Advanced → System info → Web Server → Settings file path → Open path.

3. Restart Banana Accounting Plus.

Default base URLs:

Authentication uses the X-Banana-Access-Token HTTP header. A wrong/missing token returns 401 unauthorized.

See the official docs: Integrated Web Server, Setup (macOS), API V2 Get Data, and API V2 Send Data.

Installation

The published package is @axlabs/banana-mcp-server. You usually don't need to install it explicitly — MCP clients can run it on demand with npx:

npx -y @axlabs/banana-mcp-server

Or install it globally to get the banana-mcp-server command:

npm install -g @axlabs/banana-mcp-server
banana-mcp-server

To build from source instead:

npm install
npm run build

Configuration

The server is configured entirely through environment variables:

Copy .env.example to get started.

Usage

As a standalone command

BANANA_BASE_URL="http://127.0.0.1:8081" \
BANANA_ACCESS_TOKEN="my-super-secret-access-token" \
npx -y @axlabs/banana-mcp-server

(Or node dist/index.js when running from a local build.) The server speaks MCP over stdio. Diagnostic output goes to stderr so it never corrupts the JSON-RPC stream on stdout.

Claude Desktop / Cursor configuration

Add an entry to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json, or .cursor/mcp.json):

{
  "mcpServers": {
    "banana": {
      "command": "npx",
      "args": ["-y", "@axlabs/banana-mcp-server"],
      "env": {
        "BANANA_BASE_URL": "http://127.0.0.1:8081",
        "BANANA_ACCESS_TOKEN": "my-super-secret-access-token"
      }
    }
  }
}

Prefer a pinned version in production, e.g. "@axlabs/banana-mcp-server@0.1.0". To run a local build instead, use "command": "node" with "args": ["/absolute/path/to/banana-mcp-server/dist/index.js"].

On macOS with the SSL web server, use https://127.0.0.1:8089 and add "BANANA_INSECURE_TLS": "true" (or trust the banana.localhost certificate in Keychain Access).

How an LLM should use it

1. Call banana_list_documents to discover the open accounting files.

2. Pass the returned file name (e.g. accounting.ac2) as the doc argument to other tools — or set BANANA_DEFAULT_DOC and omit it.

3. Use the read tools to answer questions, and banana_create_document to create new files.

Conventions used throughout the API: dates are ISO 8601 (YYYY-MM-DD), decimals use a dot separator with no thousands separator (see the "Data formats" section of the docs), and previous-year files are addressed by suffixing the document name with _p1, _p2, etc. Many period arguments accept abbreviations like Q1, 3M, 1Y or explicit ranges like 2024-01-01/2024-03-31.

Tool reference

All tools are namespaced with the banana_ prefix. Reads default to JSON output where the API supports it. The read tools map to the API V2 Get Data reference; the file-creation tools map to the API V2 Send Data reference.

Application & discovery

Tables

Chart of accounts

Balances, budget, interest & projection

{type} is one of opening, credit, debit, total, balance, openingcurrency, creditcurrency, debitcurrency, totalcurrency, balancecurrency, rowcount. VAT types are taxable, amount, notdeductible, posted, rowcount. The {acc} selector accepts an account id, Gr=<group>, BClass=<class>, or pipe-separated accounts like 1000|1010.

Account cards (ledgers)

Reports & document metadata

Web-app data & system

Creating files (Send Data)

banana_create_document accepts either an accountingType ({ docGroup, docApp, decimals } — e.g. docGroup: 100 double entry, docApp: 100 without VAT / 110 with VAT) or an ac2_base64 template plus a title, and a tables array describing the rows to add / modify / delete. Internally it builds a Banana DocumentChange envelope (see also Modify Data and the Excel Office Script example).

Development

npm run dev        # run from source with watch (tsx)
npm run typecheck  # tsc --noEmit
npm run lint       # eslint
npm test           # vitest (unit + in-memory MCP integration tests)
npm run build      # compile to dist/

Tests run fully offline against a mocked fetch and an in-memory MCP transport, so they do not require a running Banana instance.

Publishing (maintainers)

The package is published to npm as the public scoped package @axlabs/banana-mcp-server. prepublishOnly compiles the TypeScript to dist/ first.

npm version <patch|minor|major>
npm publish            # access:public is set via publishConfig

Project layout

src/
  index.ts          # stdio entry point
  server.ts         # builds the McpServer and registers tools
  config.ts         # environment configuration
  client.ts         # HTTP client for the Banana web server
  types.ts          # DocumentChange types + builder
  tools/            # one module per API area, all registered via tools/index.ts
test/               # vitest suites

License

Apache License 2.0 © AxLabs. See LICENSE and NOTICE.