Banana Accounting MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Banana Accounting MCP Server Show my account balances for the current year."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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).
Related MCP server: Actual Budget MCP Server
Enabling the Banana Web Server
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).
Edit
httpconfig.iniand set anaccessTokenunder the[Banana]section, and setaccessControlAllowOrigin=*(see Web Server security). To locate the file: Tools → Program Options → Advanced → System info → Web Server → Settings file path → Open path.Restart Banana Accounting Plus.
Default base URLs:
Platform | Base URL |
Windows (plain HTTP) |
|
macOS (SSL) |
|
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-serverOr install it globally to get the banana-mcp-server command:
npm install -g @axlabs/banana-mcp-server
banana-mcp-serverTo build from source instead:
npm install
npm run buildConfiguration
The server is configured entirely through environment variables:
Variable | Default | Description |
|
| Base URL of the Banana web server (no trailing slash). |
| (empty) | Access token from |
| (none) | Optional default document name so tools can omit the |
|
| Per-request timeout in milliseconds. |
|
| Set to |
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:8089and add"BANANA_INSECURE_TLS": "true"(or trust thebanana.localhostcertificate in Keychain Access).
How an LLM should use it
Call
banana_list_documentsto discover the open accounting files.Pass the returned file name (e.g.
accounting.ac2) as thedocargument to other tools — or setBANANA_DEFAULT_DOCand omit it.Use the read tools to answer questions, and
banana_create_documentto 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 |
|
| App info (version, serial, OS); optionally a single field. |
|
| Application version string. |
|
| List open accounting documents. |
|
| List available requests for a document (HTML). |
|
| List the tables in a document. |
Tables
Tool | Endpoint | Description |
|
| Read a table (view/columns/format). |
|
| Number of rows in a table. |
|
| Column XML names of a table. |
|
| A single cell value (row number or |
|
| Named row lists of a table. |
|
| Read a named row list. |
|
| Row count of a row list. |
|
| A cell within a row list. |
Chart of accounts
Tool | Endpoint | Description |
|
| List accounts. |
|
| Account/group description. |
|
| List groups. |
|
| List segments. |
|
| List VAT codes. |
|
| VAT code description. |
Balances, budget, interest & projection
Tool | Endpoint | Description |
|
| Current balance figure. |
|
| Budget figure. |
|
| Calculated interest (requires |
|
| Interest on budget transactions. |
|
| Projection figure (requires |
|
| Current VAT balance. |
|
| Budget VAT figure. |
|
| VAT projection (requires |
{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 |
|
| Transactions making up an account. |
|
| Budget transactions for an account. |
|
| Projection card (requires |
|
| Account card for a VAT code. |
Reports & document metadata
Tool | Endpoint | Description |
|
| Accounting report (with |
|
| VAT report. |
|
| Journal of all transactions. |
|
| Start date of accounting/period. |
|
| End date of accounting/period. |
|
| File info table. |
|
| A single file-info value. |
|
| All file infos as JSON. |
|
| Validation/error messages ( |
|
| Count of error messages. |
Web-app data & system
Tool | Endpoint | Description |
|
| Read stored web-app data. |
|
| Save web-app data. |
|
| Delete web-app data. |
|
| HTML form to manage app data. |
|
| Web server settings page. |
|
| Web server help page. |
|
| Read a file from the user data folder. |
|
| Execute a Banana JavaScript file. |
|
| Built-in WWW app ( |
|
| The JavaScript API helper file. |
Creating files (Send Data)
Tool | Endpoint | Description |
|
| Create & show a new file from a high-level list of per-table row changes. |
|
| Post a raw |
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 publishConfigProject 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 suitesLicense
Available Tools
53 toolsbanana_account_cardAccount cardARead-only
Return the account card (ledger of transactions) for an account. Defaults to JSON. Supports view, columns, navigation, period and filter.
Inputs: account (required), doc, view, filter, +4 more.
banana_account_descriptionAccount/group descriptionARead-only
Return the description of an account or group. Use "Gr=" to target a group. Optionally return a specific column instead of the default Description.
Inputs: account (required), doc, column.
banana_accounting_reportAccounting reportARead-only
Return the accounting report (enhanced balance sheet / P&L) for a document. Defaults to JSON. Supports view, columns, navigation, period and subdivision.
Inputs: doc, view, format, period, +3 more.
banana_accountsList accountsARead-only
Return the list of accounts as a JSON array of {id, descr} objects (e.g. [{"id":"1000","descr":"1000 Cash"}]).
Inputs: doc.
banana_api_jsJavaScript API fileARead-only
Return the bananaapiv2.js JavaScript file that defines an object-oriented interface to the web server for a given document.
Inputs: doc.
banana_appdata_deleteDelete app dataA
Delete the stored web-app data for a given data id.
Inputs: data_id (required).
banana_appdata_formApp data formARead-only
Return the HTML form used to create, modify or delete app data (/v2/appdataform).
Inputs: no named parameters.
banana_appdata_getGet app dataBRead-only
Return the stored web-app data for a given data id.
Inputs: data_id (required).
banana_appdata_putSave app dataB
Save web-app data under a data id. The data is sent as the request body. Provide a JSON object/array (sent as JSON) or a raw string.
Inputs: data (required), data_id (required).
banana_applicationApplication infoARead-only
Get information about the running Banana Accounting application (version, serial, OS, Qt version, channel). Optionally request a single value by name (e.g. "serial", "version", "name").
Inputs: value_name.
banana_application_versionApplication versionARead-only
Get the Banana Accounting application version string (e.g. "10.2.5.26020").
Inputs: no named parameters.
banana_balanceAccount balanceARead-only
Return the current accounting balance figure for an account, group or balance class. Use _p1/_p2 doc suffixes for previous years. Supports period, frequency and filter.
Inputs: type (required), account (required), doc, filter, +2 more.
banana_budgetAccount budgetARead-only
Return the budget figure for an account, group or balance class. Supports period, frequency and filter.
Inputs: type (required), account (required), doc, filter, +2 more.
banana_budget_cardBudget account cardBRead-only
Return the budget card (budget transactions) for an account. Defaults to JSON.
Inputs: account (required), doc, view, filter, +4 more.
banana_budget_interestBudget interestCRead-only
Return the calculated interest on an account/group/class for budget transactions.
Inputs: rate (required), account (required), doc, filter, +2 more.
banana_cellRead cell valueARead-only
Return the value of a single cell, identified by table, row selector, and column XML name.
Inputs: row (required), table (required), column (required), doc.
banana_create_documentCreate document (high level)A
Create a NEW accounting file in Banana and show it, applying row changes table by table. This opens a new accounting window in Banana for the user to review; it does not modify an already-open file. Provide either accountingType (new file from scratch) or ac2_base64 + title (new file based on an existing .ac2 template).
Inputs: tables (required), show, title, ac2_base64, +1 more.
banana_create_document_rawCreate document (raw payload)A
Escape hatch for the Send Data API: POST a raw request body to /v2/doc. The body must match Banana's expected shape: { fileType: {...}, data: }. Use banana_create_document for the common cases.
Inputs: body (required), show.
banana_document_requestsList document requestsARead-only
Return the HTML page listing all available HTTP requests/endpoints for a given document. Useful for discovering what data a specific accounting file exposes.
Inputs: doc.
banana_end_periodEnd period dateARead-only
Return the end date (YYYY-MM-DD) of the accounting or of a given period abbreviation.
Inputs: doc, period.
banana_fileRead user fileARead-only
Return a file stored in Banana's user data folder (/v2/files/{file_name}), e.g. "httpconfig.ini".
Inputs: file_name (required).
banana_groupsList groupsARead-only
Return the list of accounting groups as a JSON array of {id, descr} objects (e.g. [{"id":"100","descr":"100 Current Assets"}]).
Inputs: doc.
banana_helpWeb server helpARead-only
Return the web server help page (/v2/help).
Inputs: no named parameters.
banana_infosDocument infosARead-only
Return all file infos for a document as a JSON array of {section, id, value} objects.
Inputs: doc.
banana_info_tableInfo tableBRead-only
Return the file info table for a document. Defaults to JSON.
Inputs: doc, format, columns, navigation.
banana_info_valueInfo valueARead-only
Return a single file-info value, addressed by section name and id name (e.g. section "AccountingDataBase", id "BasicCurrency").
Inputs: id (required), section (required), doc.
banana_interestAccount interestARead-only
Return the calculated interest on an account/group/class. Positive rate calculates interest on debit amounts, negative on credit amounts.
Inputs: rate (required), account (required), doc, filter, +2 more.
banana_journalJournalARead-only
Return the journal (all transactions in chronological/posting order) for a document. Defaults to JSON.
Inputs: doc, format, columns, navigation.
banana_list_documentsList open documentsARead-only
List the accounting documents currently open in Banana Accounting as a JSON array of file names (e.g. ["accounting.ac2"]). Start here to discover the doc value used by other tools. Returns an empty array if no file is open.
Inputs: no named parameters.
banana_messagesValidation messagesARead-only
Return the list of accounting validation/error messages as a JSON array. Set recheck=true to force a fresh 'Recheck accounting' before returning.
Inputs: doc, recheck.
banana_messages_countValidation message countARead-only
Return the number of error messages in the accounting file as text. Set recheck=true to force a fresh 'Recheck accounting' first.
Inputs: doc, recheck.
banana_projectionAccount projectionARead-only
Return the projection figure for an account, group or balance class. Requires projectionstart. Supports period, frequency and filter.
Inputs: type (required), account (required), projectionstart (required), doc, +3 more.
banana_projection_cardProjection account cardBRead-only
Return the projection card for an account. Requires projectionstart. Defaults to JSON.
Inputs: account (required), projectionstart (required), doc, view, +5 more.
banana_rowlistRead row listARead-only
Return the content of a named row list within a table. Defaults to JSON.
Inputs: table (required), rowlist (required), doc, view, +3 more.
banana_rowlist_cellRead row list cellARead-only
Return the value of a single cell within a named row list, identified by table, row list, row selector, and column XML name.
Inputs: row (required), table (required), column (required), rowlist (required), +1 more.
banana_rowlist_namesList row listsARead-only
Return the names of the row lists present in a table as a JSON array (e.g. ["Data", "Examples", "Archives"]).
Inputs: table (required), doc.
banana_rowlist_rowcountRow list row countBRead-only
Return the number of rows in a named row list of a table as text.
Inputs: table (required), rowlist (required), doc.
banana_run_scriptExecute scriptA
Execute a Banana JavaScript file on the server (/v2/script). The script path can be absolute or relative to the user's document directory. Optionally pass a document and input data to the script.
Inputs: scriptfile (required), indata, ac2file.
banana_segmentsList segmentsARead-only
Return the list of segments as a JSON array of {id, descr} objects.
Inputs: doc.
banana_settingsWeb server settingsARead-only
Return the Banana web server settings page (/v2/settings).
Inputs: no named parameters.
banana_start_periodStart period dateARead-only
Return the start date (YYYY-MM-DD) of the accounting or of a given period abbreviation.
Inputs: doc, period.
banana_tableRead tableARead-only
Return the content of a table in a document. Defaults to JSON. Supports selecting a view, a subset of columns, and html/json output.
Inputs: table (required), doc, view, format, +2 more.
banana_table_columnsList table columnsARead-only
Return the list of column XML names for a table as a JSON array.
Inputs: table (required), doc.
banana_table_namesList table namesARead-only
List the names of all tables in a document as a JSON array (e.g. ["Accounts", "Transactions", "Budget", "FileInfo", ...]).
Inputs: doc.
banana_table_rowcountTable row countBRead-only
Return the number of rows in a table as text.
Inputs: table (required), doc.
banana_vat_balanceVAT balanceARead-only
Return the current VAT balance figure for a VAT code or VAT group. Supports period, frequency and filter.
Inputs: type (required), vat_code (required), doc, filter, +2 more.
banana_vat_budgetVAT budgetBRead-only
Return the budget VAT figure for a VAT code or VAT group.
Inputs: type (required), vat_code (required), doc, filter, +2 more.
banana_vat_cardVAT code cardARead-only
Return the account card for a VAT code (or pipe-separated codes, e.g. "V0|V80"). Defaults to JSON.
Inputs: vat_code (required), doc, view, filter, +4 more.
banana_vatcodesList VAT codesBRead-only
Return the list of VAT codes as a JSON array of {id, descr} objects (e.g. [{"id":"V80","descr":"V80 Sales and services 8.0%"}]).
Inputs: doc.
banana_vat_descriptionVAT code descriptionARead-only
Return the description of a VAT code. Optionally return a specific column instead of the default Description.
Inputs: vat_code (required), doc, column.
banana_vat_projectionVAT projectionCRead-only
Return the projection VAT figure for a VAT code or VAT group. Requires projectionstart.
Inputs: type (required), vat_code (required), projectionstart (required), doc, +3 more.
banana_vat_reportVAT reportCRead-only
Return the VAT report for a document. Defaults to JSON.
Inputs: doc, view, format, period, +2 more.
banana_www_appWWW appARead-only
Return a built-in WWW app HTML page for a document (/v2/doc/{doc}/apps/{app_name}). Known apps: "charts", "dashboard".
Inputs: app_name (required), doc.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 53 tools
Most tools have clearly distinct purposes, such as table vs. rowlist operations and various financial figures. However, there are some overlapping utilities like banana_infos, banana_info_table, and banana_info_value, which could cause confusion. Overall, descriptions help clarify boundaries.
All tool names start with the 'banana_' prefix and use underscores consistently. The naming follows a resource-oriented hierarchy (e.g., banana_vat_balance, banana_table_rowcount), making it predictable and easy to navigate.
With 53 tools, the server is heavily over the typical range for an MCP server. While the accounting domain is broad, many tools are highly specialized or could be consolidated, and the count feels excessive for most use cases.
The server provides comprehensive read access to accounting data, including tables, financial figures, reports, and documents, plus document creation. Minor gaps exist, such as lacking update/delete operations for accounting data (aside from appdata) and some discovery endpoints, but these are acceptable for a read-heavy API.
Maintenance
Related MCP Connectors
Personal finance, bank account, and shared memory connector for Claude, ChatGPT, Gemini Spark & more
Bokio MCP server for ChatGPT, Claude and any AI agent: create invoice, send invoice, upload receipt, create journal entry and list unpaid invoices in your own Bokio account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Bokio yourself; Cotlet does not store your password and you need no Bokio API key. About the official Bokio API: Yes, Bokio has a public REST API for invoices, customers, journal entries, uploads and supplier invoices (checked 14 Oct 2026), but it depends on your price plan and on the kind of integration: a private integration token works for one company only, and a tool that serves several companies must be registered as a public integration with OAuth 2.0. Bokio publishes no MCP server of its own. Setup and FAQ: https://cotlet.dev/integrations/bokio-api-mcp-server
Connect ChatGPT and Claude to Fortnox: invoices, customers, reports. Every write needs your OK.
Fatture in Cloud MCP server for ChatGPT, Claude and any AI agent: create invoice, send to SDI, add client, record expense and list unpaid invoices in your own Fatture in Cloud account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Fatture in Cloud yourself; Cotlet does not store your password and you need no Fatture in Cloud API key. About the official Fatture in Cloud API: Yes, Fatture in Cloud has a documented REST API (v2) for issued invoices, clients, received documents, e-invoices to SDI and attachments (checked 14 Oct 2026), but it has no official MCP server. To use it you register an OAuth 2.0 app, or create a manual access token in the web app, choose scopes and pick the companies the token applies to. Setup and FAQ: https://cotlet.dev/integrations/fatture-in-cloud-api-mcp-server
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceConnects Claude Desktop to the MonKey Office Connect JSON-API, enabling natural language queries for accounting data like bookings, invoices, and open items. It allows users to retrieve information about companies, accounts, customers, and projects through a set of specialized tools.-
- AlicenseAqualityCmaintenanceEnables LLMs to interact with a self-hosted Actual Budget instance, providing financial data and management tools with correct financial semantics and no cents math.113MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to query and manage self-hosted accounting data—invoices, balances, and books—through natural language, with read-only tools by default and optional scoped write operations.3027 PyPI1AGPL 3.0
- FlicenseNot gradedqualityCmaintenanceEnables connecting AI assistants to Exact Online through its official REST API with OAuth2 authentication and automatic token refresh. Provides curated tools for reading and, optionally, writing common accounting entities such as accounts, contacts, items, journal entries and sales/purchase invoices, plus generic GET/POST/PUT/DELETE tools for any other endpoint, over local stdio or hosted HTTP transports.1-