Banana Accounting 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:

Platform	Base URL
Windows (plain HTTP)	http://127.0.0.1:8081
macOS (SSL)	https://127.0.0.1:8089

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:

Variable	Default	Description
BANANA_BASE_URL	http://127.0.0.1:8081	Base URL of the Banana web server (no trailing slash).
BANANA_ACCESS_TOKEN	(empty)	Access token from httpconfig.ini. Sent as X-Banana-Access-Token.
BANANA_DEFAULT_DOC	(none)	Optional default document name so tools can omit the doc argument.
BANANA_TIMEOUT_MS	30000	Per-request timeout in milliseconds.
BANANA_INSECURE_TLS	false	Set to true to accept the self-signed certificate used by the macOS SSL server.

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/[email protected]". 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

Tool	Endpoint	Description
banana_application	/v2/application[/{value}]	App info (version, serial, OS); optionally a single field.
banana_application_version	/v2/application/version	Application version string.
banana_list_documents	/v2/docs	List open accounting documents.
banana_document_requests	/v2/doc/{doc}	List available requests for a document (HTML).
banana_table_names	/v2/doc/{doc}/tablenames	List the tables in a document.

Tables

Tool	Endpoint	Description
banana_table	/v2/doc/{doc}/table/{table}	Read a table (view/columns/format).
banana_table_rowcount	.../rowcount	Number of rows in a table.
banana_table_columns	.../columnnames	Column XML names of a table.
banana_cell	.../row/{row}/column/{col}	A single cell value (row number or Account=1000).
banana_rowlist_names	.../rowlistnames	Named row lists of a table.
banana_rowlist	.../rowlist/{name}	Read a named row list.
banana_rowlist_rowcount	.../rowlist/{name}/rowcount	Row count of a row list.
banana_rowlist_cell	.../rowlist/{name}/row/{row}/column/{col}	A cell within a row list.

Chart of accounts

Tool	Endpoint	Description
banana_accounts	/v2/doc/{doc}/accounts	List accounts.
banana_account_description	/v2/doc/{doc}/accountdescription/{acc|Gr=id}[/{col}]	Account/group description.
banana_groups	/v2/doc/{doc}/groups	List groups.
banana_segments	/v2/doc/{doc}/segments	List segments.
banana_vatcodes	/v2/doc/{doc}/vatcodes	List VAT codes.
banana_vat_description	/v2/doc/{doc}/vatdescription/{code}[/{col}]	VAT code description.

Balances, budget, interest & projection

Tool	Endpoint	Description
banana_balance	/v2/doc/{doc}/balance/{acc}/{type}	Current balance figure.
banana_budget	/v2/doc/{doc}/budget/{acc}/{type}	Budget figure.
banana_interest	/v2/doc/{doc}/interest/{acc}	Calculated interest (requires rate).
banana_budget_interest	/v2/doc/{doc}/budgetinterest/{acc}	Interest on budget transactions.
banana_projection	/v2/doc/{doc}/projection/{acc}/{type}	Projection figure (requires projectionstart).
banana_vat_balance	/v2/doc/{doc}/vatbalance/{code}/{type}	Current VAT balance.
banana_vat_budget	/v2/doc/{doc}/vatbudget/{code}/{type}	Budget VAT figure.
banana_vat_projection	/v2/doc/{doc}/vatprojection/{code}/{type}	VAT projection (requires projectionstart).

{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)

Tool	Endpoint	Description
banana_account_card	/v2/doc/{doc}/accountcard/{acc}	Transactions making up an account.
banana_budget_card	/v2/doc/{doc}/budgetcard/{acc}	Budget transactions for an account.
banana_projection_card	/v2/doc/{doc}/projectioncard/{acc}	Projection card (requires projectionstart).
banana_vat_card	/v2/doc/{doc}/vatcard/{code}	Account card for a VAT code.

Reports & document metadata

Tool	Endpoint	Description
banana_accounting_report	/v2/doc/{doc}/accreport	Accounting report (with subdivision).
banana_vat_report	/v2/doc/{doc}/vatreport	VAT report.
banana_journal	/v2/doc/{doc}/journal	Journal of all transactions.
banana_start_period	/v2/doc/{doc}/startperiod	Start date of accounting/period.
banana_end_period	/v2/doc/{doc}/endPeriod	End date of accounting/period.
banana_info_table	/v2/doc/{doc}/info	File info table.
banana_info_value	/v2/doc/{doc}/info/{section}/{id}	A single file-info value.
banana_infos	/v2/doc/{doc}/infos	All file infos as JSON.
banana_messages	/v2/doc/{doc}/messages	Validation/error messages (recheck).
banana_messages_count	/v2/doc/{doc}/messages/count	Count of error messages.

Web-app data & system

Tool	Endpoint	Description
banana_appdata_get	GET /v2/appdata/{id}	Read stored web-app data.
banana_appdata_put	PUT /v2/appdata/{id}	Save web-app data.
banana_appdata_delete	DELETE /v2/appdata/{id}	Delete web-app data.
banana_appdata_form	/v2/appdataform	HTML form to manage app data.
banana_settings	/v2/settings	Web server settings page.
banana_help	/v2/help	Web server help page.
banana_file	/v2/files/{name}	Read a file from the user data folder.
banana_run_script	/v2/script	Execute a Banana JavaScript file.
banana_www_app	/v2/doc/{doc}/apps/{name}	Built-in WWW app (charts, dashboard).
banana_api_js	/v2/doc/{doc}/bananaapiv2.js	The JavaScript API helper file.

Creating files (Send Data)

Tool	Endpoint	Description
banana_create_document	POST /v2/doc?show	Create & show a new file from a high-level list of per-table row changes.
banana_create_document_raw	POST /v2/doc?show	Post a raw { fileType, data } payload (escape hatch).

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.