{"_id":"@axlabs/banana-mcp-server","name":"@axlabs/banana-mcp-server","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@axlabs/banana-mcp-server","version":"0.1.0","description":"Model Context Protocol (MCP) server exposing the full Banana Accounting Plus Integrated Web Server API V2 to LLMs.","license":"Apache-2.0","author":{"name":"AxLabs"},"repository":{"type":"git","url":"git+https://github.com/AxLabs/banana-mcp-server.git"},"homepage":"https://github.com/AxLabs/banana-mcp-server#readme","bugs":{"url":"https://github.com/AxLabs/banana-mcp-server/issues"},"type":"module","bin":{"banana-mcp-server":"dist/index.js"},"main":"dist/index.js","publishConfig":{"access":"public"},"engines":{"node":">=18"},"scripts":{"build":"tsc","dev":"tsx watch src/index.ts","start":"node dist/index.js","typecheck":"tsc --noEmit","lint":"eslint .","lint:fix":"eslint . --fix","format":"prettier --write .","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run build"},"keywords":["mcp","model-context-protocol","banana","banana-accounting","accounting","llm","ai"],"dependencies":{"@modelcontextprotocol/sdk":"^1.18.0","zod":"^3.23.8"},"devDependencies":{"@eslint/js":"^9.17.0","@types/node":"^22.10.0","eslint":"^9.17.0","prettier":"^3.4.2","tsx":"^4.19.2","typescript":"^5.7.2","typescript-eslint":"^8.18.0","vitest":"^2.1.8"},"_id":"@axlabs/banana-mcp-server@0.1.0","gitHead":"5b088a268ad17e0e7ac024cc14c5b34aaa6aa89f","types":"./dist/index.d.ts","_nodeVersion":"24.8.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-qLma/Y4cKXXrrlcxEBbh9AypGKKlI0HxRjFj4gSxWX/x1i6jvW1zzDgt8PLPeMAyoz8SUQE34VFIGXlHf+GD+w==","shasum":"7f850fc58084654bc55589a20ffbd0eeeac79dbb","tarball":"https://registry.npmjs.org/@axlabs/banana-mcp-server/-/banana-mcp-server-0.1.0.tgz","fileCount":72,"unpackedSize":141298,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFoNR0G9K2RuyyRxLy3Cc/aIr5BHMZCNNS2OBFQH9KbpAiBUeUp83xVguhwlOsAwwy37bY2b5iIqR18l/TCL9YqV0Q=="}]},"_npmUser":{"name":"gsperbmachado","email":"guil@axlabs.com"},"directories":{},"maintainers":[{"name":"merl123","email":"mathias@axlabs.com"},{"name":"axlabs-bot","email":"tech@axlabs.com"},{"name":"mialbu","email":"bucher_michael@hotmail.com"},{"name":"gsperbmachado","email":"guil@axlabs.com"},{"name":"thedanielmark","email":"danielmark.uc@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/banana-mcp-server_0.1.0_1781032613092_0.2757410489085228"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-09T19:16:52.898Z","0.1.0":"2026-06-09T19:16:53.246Z","modified":"2026-06-09T19:16:53.507Z"},"maintainers":[{"name":"merl123","email":"mathias@axlabs.com"},{"name":"axlabs-bot","email":"tech@axlabs.com"},{"name":"mialbu","email":"bucher_michael@hotmail.com"},{"name":"gsperbmachado","email":"guil@axlabs.com"},{"name":"thedanielmark","email":"danielmark.uc@gmail.com"}],"description":"Model Context Protocol (MCP) server exposing the full Banana Accounting Plus Integrated Web Server API V2 to LLMs.","homepage":"https://github.com/AxLabs/banana-mcp-server#readme","keywords":["mcp","model-context-protocol","banana","banana-accounting","accounting","llm","ai"],"repository":{"type":"git","url":"git+https://github.com/AxLabs/banana-mcp-server.git"},"author":{"name":"AxLabs"},"bugs":{"url":"https://github.com/AxLabs/banana-mcp-server/issues"},"license":"Apache-2.0","readme":"# Banana Accounting MCP Server\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, written in\nTypeScript, that exposes the **Banana Accounting Plus\n[Integrated Web Server](https://www.banana.ch/doc/en/node/4867) API V2** to LLMs. Point\nyour MCP-capable client (Claude Desktop, Cursor, etc.) at this server and the model can\nread your accounts, balances, journals, reports and VAT data — and create new accounting\nfiles — directly from your locally running Banana Accounting instance.\n\nEvery documented endpoint from the\n[API V2 Get Data](https://www.banana.ch/doc10/en/node/10022) and\n[Send Data](https://www.banana.ch/doc10/en/node/9841) references is exposed as a dedicated\ntool. See the [full tool reference](#tool-reference) below.\n\n> The Banana Integrated Web Server is **read-only for existing files** — for security it\n> cannot modify an open accounting file. The only write operation it offers is creating a\n> *new* file (which Banana opens for you to review). This server mirrors that capability\n> faithfully.\n\n## Requirements\n\n- **Node.js >= 18** (uses the built-in global `fetch`).\n- **Banana Accounting Plus 10.1.7+** with the **Advanced plan** (the\n  [Web Server feature](https://www.banana.ch/doc/en/node/4867) requires it).\n- The [Integrated Web Server](https://www.banana.ch/doc/en/node/4867) enabled and reachable\n  (see below).\n\n## Enabling the Banana Web Server\n\n1. In Banana Accounting Plus: **Tools → Program Options → General**, check\n   **Start Web Server** (on macOS also **Start Web Server with SSL** — see the\n   [macOS setup guide](https://www.banana.ch/doc/en/node/10029)).\n2. Edit `httpconfig.ini` and set an `accessToken` under the `[Banana]` section, and set\n   `accessControlAllowOrigin=*` (see [Web Server security](https://www.banana.ch/doc/en/node/4867)).\n   To locate the file: **Tools → Program Options → Advanced → System info → Web Server →\n   Settings file path → Open path**.\n3. Restart Banana Accounting Plus.\n\nDefault base URLs:\n\n| Platform | Base URL |\n| --- | --- |\n| Windows (plain HTTP) | `http://127.0.0.1:8081` |\n| macOS (SSL)          | `https://127.0.0.1:8089` |\n\nAuthentication uses the `X-Banana-Access-Token` HTTP header. A wrong/missing token returns\n`401 unauthorized`.\n\nSee the official docs: [Integrated Web Server](https://www.banana.ch/doc/en/node/4867),\n[Setup (macOS)](https://www.banana.ch/doc/en/node/10029),\n[API V2 Get Data](https://www.banana.ch/doc10/en/node/10022), and\n[API V2 Send Data](https://www.banana.ch/doc10/en/node/9841).\n\n## Installation\n\nThe published package is [`@axlabs/banana-mcp-server`](https://www.npmjs.com/package/@axlabs/banana-mcp-server).\nYou usually don't need to install it explicitly — MCP clients can run it on demand with\n`npx`:\n\n```bash\nnpx -y @axlabs/banana-mcp-server\n```\n\nOr install it globally to get the `banana-mcp-server` command:\n\n```bash\nnpm install -g @axlabs/banana-mcp-server\nbanana-mcp-server\n```\n\nTo build from source instead:\n\n```bash\nnpm install\nnpm run build\n```\n\n## Configuration\n\nThe server is configured entirely through environment variables:\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `BANANA_BASE_URL` | `http://127.0.0.1:8081` | Base URL of the Banana web server (no trailing slash). |\n| `BANANA_ACCESS_TOKEN` | _(empty)_ | Access token from `httpconfig.ini`. Sent as `X-Banana-Access-Token`. |\n| `BANANA_DEFAULT_DOC` | _(none)_ | Optional default document name so tools can omit the `doc` argument. |\n| `BANANA_TIMEOUT_MS` | `30000` | Per-request timeout in milliseconds. |\n| `BANANA_INSECURE_TLS` | `false` | Set to `true` to accept the self-signed certificate used by the macOS SSL server. |\n\nCopy `.env.example` to get started.\n\n## Usage\n\n### As a standalone command\n\n```bash\nBANANA_BASE_URL=\"http://127.0.0.1:8081\" \\\nBANANA_ACCESS_TOKEN=\"my-super-secret-access-token\" \\\nnpx -y @axlabs/banana-mcp-server\n```\n\n(Or `node dist/index.js` when running from a local build.) The server speaks MCP over\n**stdio**. Diagnostic output goes to `stderr` so it never corrupts the JSON-RPC stream on\n`stdout`.\n\n### Claude Desktop / Cursor configuration\n\nAdd an entry to your MCP client config (e.g. Claude Desktop's\n`claude_desktop_config.json`, or `.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"banana\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@axlabs/banana-mcp-server\"],\n      \"env\": {\n        \"BANANA_BASE_URL\": \"http://127.0.0.1:8081\",\n        \"BANANA_ACCESS_TOKEN\": \"my-super-secret-access-token\"\n      }\n    }\n  }\n}\n```\n\n> Prefer a pinned version in production, e.g. `\"@axlabs/banana-mcp-server@0.1.0\"`. To run a\n> local build instead, use `\"command\": \"node\"` with\n> `\"args\": [\"/absolute/path/to/banana-mcp-server/dist/index.js\"]`.\n\n> On macOS with the SSL web server, use `https://127.0.0.1:8089` and add\n> `\"BANANA_INSECURE_TLS\": \"true\"` (or trust the `banana.localhost` certificate in\n> Keychain Access).\n\n## How an LLM should use it\n\n1. Call **`banana_list_documents`** to discover the open accounting files.\n2. Pass the returned file name (e.g. `accounting.ac2`) as the **`doc`** argument to other\n   tools — or set `BANANA_DEFAULT_DOC` and omit it.\n3. Use the read tools to answer questions, and `banana_create_document` to create new\n   files.\n\n[Conventions](https://www.banana.ch/doc/en/node/4867) used throughout the API: dates are\nISO 8601 (`YYYY-MM-DD`), decimals use a dot separator with no thousands separator (see the\n\"Data formats\" section of the docs), and previous-year files are addressed by suffixing\nthe document name with `_p1`, `_p2`, etc. Many `period` arguments accept abbreviations\nlike `Q1`, `3M`, `1Y` or explicit ranges like `2024-01-01/2024-03-31`.\n\n## Tool reference\n\nAll tools are namespaced with the `banana_` prefix. Reads default to JSON output where the\nAPI supports it. The read tools map to the\n[API V2 Get Data](https://www.banana.ch/doc10/en/node/10022) reference; the file-creation\ntools map to the [API V2 Send Data](https://www.banana.ch/doc10/en/node/9841) reference.\n\n### Application & discovery\n\n| Tool | Endpoint | Description |\n| --- | --- | --- |\n| `banana_application` | `/v2/application[/{value}]` | App info (version, serial, OS); optionally a single field. |\n| `banana_application_version` | `/v2/application/version` | Application version string. |\n| `banana_list_documents` | `/v2/docs` | List open accounting documents. |\n| `banana_document_requests` | `/v2/doc/{doc}` | List available requests for a document (HTML). |\n| `banana_table_names` | `/v2/doc/{doc}/tablenames` | List the tables in a document. |\n\n### Tables\n\n| Tool | Endpoint | Description |\n| --- | --- | --- |\n| `banana_table` | `/v2/doc/{doc}/table/{table}` | Read a table (view/columns/format). |\n| `banana_table_rowcount` | `.../rowcount` | Number of rows in a table. |\n| `banana_table_columns` | `.../columnnames` | Column XML names of a table. |\n| `banana_cell` | `.../row/{row}/column/{col}` | A single cell value (row number or `Account=1000`). |\n| `banana_rowlist_names` | `.../rowlistnames` | Named row lists of a table. |\n| `banana_rowlist` | `.../rowlist/{name}` | Read a named row list. |\n| `banana_rowlist_rowcount` | `.../rowlist/{name}/rowcount` | Row count of a row list. |\n| `banana_rowlist_cell` | `.../rowlist/{name}/row/{row}/column/{col}` | A cell within a row list. |\n\n### Chart of accounts\n\n| Tool | Endpoint | Description |\n| --- | --- | --- |\n| `banana_accounts` | `/v2/doc/{doc}/accounts` | List accounts. |\n| `banana_account_description` | `/v2/doc/{doc}/accountdescription/{acc\\|Gr=id}[/{col}]` | Account/group description. |\n| `banana_groups` | `/v2/doc/{doc}/groups` | List groups. |\n| `banana_segments` | `/v2/doc/{doc}/segments` | List segments. |\n| `banana_vatcodes` | `/v2/doc/{doc}/vatcodes` | List VAT codes. |\n| `banana_vat_description` | `/v2/doc/{doc}/vatdescription/{code}[/{col}]` | VAT code description. |\n\n### Balances, budget, interest & projection\n\n| Tool | Endpoint | Description |\n| --- | --- | --- |\n| `banana_balance` | `/v2/doc/{doc}/balance/{acc}/{type}` | Current balance figure. |\n| `banana_budget` | `/v2/doc/{doc}/budget/{acc}/{type}` | Budget figure. |\n| `banana_interest` | `/v2/doc/{doc}/interest/{acc}` | Calculated interest (requires `rate`). |\n| `banana_budget_interest` | `/v2/doc/{doc}/budgetinterest/{acc}` | Interest on budget transactions. |\n| `banana_projection` | `/v2/doc/{doc}/projection/{acc}/{type}` | Projection figure (requires `projectionstart`). |\n| `banana_vat_balance` | `/v2/doc/{doc}/vatbalance/{code}/{type}` | Current VAT balance. |\n| `banana_vat_budget` | `/v2/doc/{doc}/vatbudget/{code}/{type}` | Budget VAT figure. |\n| `banana_vat_projection` | `/v2/doc/{doc}/vatprojection/{code}/{type}` | VAT projection (requires `projectionstart`). |\n\n`{type}` is one of `opening`, `credit`, `debit`, `total`, `balance`,\n`openingcurrency`, `creditcurrency`, `debitcurrency`, `totalcurrency`,\n`balancecurrency`, `rowcount`. VAT types are `taxable`, `amount`, `notdeductible`,\n`posted`, `rowcount`. The `{acc}` selector accepts an account id, `Gr=<group>`,\n`BClass=<class>`, or pipe-separated accounts like `1000|1010`.\n\n### Account cards (ledgers)\n\n| Tool | Endpoint | Description |\n| --- | --- | --- |\n| `banana_account_card` | `/v2/doc/{doc}/accountcard/{acc}` | Transactions making up an account. |\n| `banana_budget_card` | `/v2/doc/{doc}/budgetcard/{acc}` | Budget transactions for an account. |\n| `banana_projection_card` | `/v2/doc/{doc}/projectioncard/{acc}` | Projection card (requires `projectionstart`). |\n| `banana_vat_card` | `/v2/doc/{doc}/vatcard/{code}` | Account card for a VAT code. |\n\n### Reports & document metadata\n\n| Tool | Endpoint | Description |\n| --- | --- | --- |\n| `banana_accounting_report` | `/v2/doc/{doc}/accreport` | Accounting report (with `subdivision`). |\n| `banana_vat_report` | `/v2/doc/{doc}/vatreport` | VAT report. |\n| `banana_journal` | `/v2/doc/{doc}/journal` | Journal of all transactions. |\n| `banana_start_period` | `/v2/doc/{doc}/startperiod` | Start date of accounting/period. |\n| `banana_end_period` | `/v2/doc/{doc}/endPeriod` | End date of accounting/period. |\n| `banana_info_table` | `/v2/doc/{doc}/info` | File info table. |\n| `banana_info_value` | `/v2/doc/{doc}/info/{section}/{id}` | A single file-info value. |\n| `banana_infos` | `/v2/doc/{doc}/infos` | All file infos as JSON. |\n| `banana_messages` | `/v2/doc/{doc}/messages` | Validation/error messages (`recheck`). |\n| `banana_messages_count` | `/v2/doc/{doc}/messages/count` | Count of error messages. |\n\n### Web-app data & system\n\n| Tool | Endpoint | Description |\n| --- | --- | --- |\n| `banana_appdata_get` | `GET /v2/appdata/{id}` | Read stored web-app data. |\n| `banana_appdata_put` | `PUT /v2/appdata/{id}` | Save web-app data. |\n| `banana_appdata_delete` | `DELETE /v2/appdata/{id}` | Delete web-app data. |\n| `banana_appdata_form` | `/v2/appdataform` | HTML form to manage app data. |\n| `banana_settings` | `/v2/settings` | Web server settings page. |\n| `banana_help` | `/v2/help` | Web server help page. |\n| `banana_file` | `/v2/files/{name}` | Read a file from the user data folder. |\n| `banana_run_script` | `/v2/script` | Execute a Banana JavaScript file. |\n| `banana_www_app` | `/v2/doc/{doc}/apps/{name}` | Built-in WWW app (`charts`, `dashboard`). |\n| `banana_api_js` | `/v2/doc/{doc}/bananaapiv2.js` | The JavaScript API helper file. |\n\n### Creating files ([Send Data](https://www.banana.ch/doc10/en/node/9841))\n\n| Tool | Endpoint | Description |\n| --- | --- | --- |\n| `banana_create_document` | `POST /v2/doc?show` | Create & show a new file from a high-level list of per-table row changes. |\n| `banana_create_document_raw` | `POST /v2/doc?show` | Post a raw `{ fileType, data }` payload (escape hatch). |\n\n`banana_create_document` accepts either an `accountingType`\n(`{ docGroup, docApp, decimals }` — e.g. `docGroup: 100` double entry, `docApp: 100`\nwithout VAT / `110` with VAT) or an `ac2_base64` template plus a `title`, and a `tables`\narray describing the rows to `add` / `modify` / `delete`. Internally it builds a Banana\n[`DocumentChange`](https://www.banana.ch/doc10/en/node/9841) envelope (see also\n[Modify Data](https://www.banana.ch/doc/en/node/10161) and the\n[Excel Office Script example](https://www.banana.ch/doc10/en/node/10154)).\n\n## Development\n\n```bash\nnpm run dev        # run from source with watch (tsx)\nnpm run typecheck  # tsc --noEmit\nnpm run lint       # eslint\nnpm test           # vitest (unit + in-memory MCP integration tests)\nnpm run build      # compile to dist/\n```\n\nTests run fully offline against a mocked `fetch` and an in-memory MCP transport, so they\ndo not require a running Banana instance.\n\n### Publishing (maintainers)\n\nThe package is published to npm as the public scoped package\n`@axlabs/banana-mcp-server`. `prepublishOnly` compiles the TypeScript to `dist/` first.\n\n```bash\nnpm version <patch|minor|major>\nnpm publish            # access:public is set via publishConfig\n```\n\n## Project layout\n\n```\nsrc/\n  index.ts          # stdio entry point\n  server.ts         # builds the McpServer and registers tools\n  config.ts         # environment configuration\n  client.ts         # HTTP client for the Banana web server\n  types.ts          # DocumentChange types + builder\n  tools/            # one module per API area, all registered via tools/index.ts\ntest/               # vitest suites\n```\n\n## License\n\nApache License 2.0 © [AxLabs](https://axlabs.com). See [LICENSE](./LICENSE) and\n[NOTICE](./NOTICE).\n","readmeFilename":"README.md","_rev":"1-201cbcb309d3b9b06ce3d854cf5d33ab"}