{
  "markdown": "<p align=\"center\">\n  <a href=\"https://www.manager.io/\">\n    <img src=\"docs/manager-icon.svg\" alt=\"Manager.io\" width=\"72\" height=\"72\">\n  </a>\n</p>\n\n# manager-mcp\n\n<!-- mcp-name: io.github.flumpiey/manager-mcp -->\n\n**MCP server for self-hosted [Manager.io](https://www.manager.io/): ask your AI about invoices, balances, and books.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://www.python.org/)\n[![MCP](https://img.shields.io/badge/MCP-stdio-green.svg)](https://modelcontextprotocol.io/)\n[![CI](https://github.com/flumpiey/manager-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/flumpiey/manager-mcp/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/manager-mcp.svg)](https://pypi.org/project/manager-mcp/)\n\n## What is Manager.io?\n\n[Manager.io](https://www.manager.io/) is free, self-hosted accounting software for Windows, macOS, and Linux (also available as [Cloud Edition](https://www.manager.io/cloud-edition)). It covers sales, purchases, banking, payroll, and the full ledger, with an HTTP API (`/api2`) for automation.\n\nThis project wires that API into the [Model Context Protocol](https://modelcontextprotocol.io/) so Cursor, Claude, VS Code Copilot, and other MCP hosts can query your live books in natural language.\n\nUseful Manager.io links:\n\n- [Download](https://www.manager.io/download)\n- [Guides](https://www.manager.io/guides)\n- [Forum](https://forum.manager.io)\n- [Releases](https://www.manager.io/releases)\n\n## What this server does\n\nDefault is **read-only**. You get:\n\n- **10 read tools** - discovery, six searchable collections, seven report shortcuts\n- **Task tools (opt-in)** - intent-shaped writes such as `record_customer_payment`, `issue_sales_invoice`, `record_customer_deposit` (register when matching write scopes are set)\n- **Deprecated CRUD tools** - per-resource `create_*` / `update_*` / `delete_*` still register under scopes until **0.3.0**; prefer task tools\n- **`raw` escape hatch** - restores the full CRUD set for advanced use\n- **Hard denylist** - access tokens, chart of accounts forms, tax/currency, email templates, and similar high-risk paths stay blocked even when writes are on\n\nTransport is **stdio**. No HTTP server. No global install required if you use [`uv`](https://docs.astral.sh/uv/) / `uvx`.\n\n## Branding / icons\n\n- **stdio hosts (Cursor, Claude Desktop via `mcp.json`):** the server advertises Manager branding in MCP `serverInfo.icons` (embedded PNG data URI, plus a GitHub raw HTTPS fallback).\n- **Cursor plugin:** [`.cursor-plugin/plugin.json`](.cursor-plugin/plugin.json) uses [`docs/manager-icon.svg`](docs/manager-icon.svg).\n- **Claude Desktop Extension:** pack [`mcpb/`](mcpb/) (includes `icon.png`). See Installation → Claude Desktop below.\n- **Claude.ai remote connectors:** Claude.ai ignores `serverInfo.icons` and uses the **root-domain favicon** of the connector URL. If you host a remote MCP later, serve [`docs/favicon.ico`](docs/favicon.ico) at the registrable domain root (e.g. `https://acme.com/favicon.ico` for `https://mcp.acme.com/...`).\n\n## Requirements\n\n- Python ≥ 3.10 (pulled in automatically by `uvx`)\n- [uv](https://docs.astral.sh/uv/) (provides `uvx`)\n- A reachable Manager.io API: `MANAGER_API_URL` + `MANAGER_API_KEY`\n\n### Access token\n\n1. In Manager, open **Settings → Access Tokens**.\n2. Create a token and copy the value into `MANAGER_API_KEY`.\n3. Set `MANAGER_API_URL` to your API base (desktop often `http://127.0.0.1:55667/api2`).\n\n`manager-mcp` sends the token as the `X-API-KEY` header. Full walkthrough: [Access Tokens](https://www.manager.io/guides/access-tokens).\n\n## Quick start\n\nRun the [PyPI](https://pypi.org/project/manager-mcp/) package with [`uvx`](https://docs.astral.sh/uv/guides/tools/):\n\n```bash\nuvx manager-mcp\n```\n\nPaste a client config below, set `MANAGER_API_URL` / `MANAGER_API_KEY`, restart the host, then ask: *“Who owes me money?”* or *“Show bank balances.”*\n\nFrom a git clone (dev): `uvx --from git+https://github.com/flumpiey/manager-mcp manager-mcp` or `uv run --directory /path/to/manager-mcp manager-mcp`.\n\n## Installation\n\nConfigs below pull [`manager-mcp`](https://pypi.org/project/manager-mcp/) from PyPI. Leave write-scope env vars unset for read-only.\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\n**Plugin (Configure UI for URL, key, and scopes):** this repo is a Cursor plugin via [`.cursor-plugin/plugin.json`](.cursor-plugin/plugin.json) + root [`mcp.json`](mcp.json).\n\n1. Symlink or copy the clone to `~/.cursor/plugins/local/manager-mcp` (Windows: `%USERPROFILE%\\.cursor\\plugins\\local\\manager-mcp`).\n2. Reload the window.\n3. Open **Plugins → Configure** on `manager-mcp`. Set **Manager API URL** and **Manager API key**. Leave **Write scopes** / **Delete scopes** empty for read-only, or paste a CSV such as `quotes` or `quotes,orders`.\n4. Confirm the `manager` MCP server is enabled under Customize / MCP.\n\nMarketplace listing is a separate submit at [cursor.com/marketplace/publish](https://cursor.com/marketplace/publish).\n\n**Manual `mcp.json`:** project [`.cursor/mcp.json`](.cursor/mcp.json) or user-wide `~/.cursor/mcp.json`.\n\nFrom PyPI:\n\n```json\n{\n  \"mcpServers\": {\n    \"manager\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"manager-mcp\"],\n      \"env\": {\n        \"MANAGER_API_URL\": \"http://127.0.0.1:55667/api2\",\n        \"MANAGER_API_KEY\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\nLocal editable (dev):\n\n```json\n{\n  \"mcpServers\": {\n    \"manager\": {\n      \"type\": \"stdio\",\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/manager-mcp\", \"manager-mcp\"],\n      \"env\": {\n        \"MANAGER_API_URL\": \"http://127.0.0.1:55667/api2\",\n        \"MANAGER_API_KEY\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\nOptional scoped writes in the `env` block:\n\n```json\n\"MANAGER_MCP_WRITE_SCOPES\": \"quotes\",\n\"MANAGER_MCP_DELETE_SCOPES\": \"quotes\"\n```\n\nRestart Cursor after saving. Confirm `manager` under MCP settings.\n\n</details>\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\n**Desktop Extension (`.mcpb`):** download [`mcpb.mcpb`](https://github.com/flumpiey/manager-mcp/releases/latest/download/mcpb.mcpb) from [GitHub Releases](https://github.com/flumpiey/manager-mcp/releases). Use **v0.2.6** or later.\n\n1. Open Claude Desktop → **Settings → Extensions**.\n2. Open **Advanced settings** → **Install Extension…**\n3. Select `mcpb.mcpb`. Review permissions, enter **Manager API URL** and **Manager API key**, then click **Install**.\n4. Leave **Write scopes** and **Delete scopes** empty for read-only.\n5. Restart Claude Desktop if tools do not appear.\n\nBuild your own bundle from a clone:\n\n```bash\nnpx @anthropic-ai/mcpb pack mcpb\n```\n\nOn Windows, double-click often does nothing and dragging the file into chat attaches it to the conversation instead of installing it. Use **Install Extension…** in Settings.\n\n**Manual `mcp.json` config:** edit the Claude Desktop config, then restart the app.\n\n| OS | Path |\n|----|------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n\n```json\n{\n  \"mcpServers\": {\n    \"manager\": {\n      \"command\": \"uvx\",\n      \"args\": [\"manager-mcp\"],\n      \"env\": {\n        \"MANAGER_API_URL\": \"http://127.0.0.1:55667/api2\",\n        \"MANAGER_API_KEY\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\nLocal clone:\n\n```json\n{\n  \"mcpServers\": {\n    \"manager\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/manager-mcp\", \"manager-mcp\"],\n      \"env\": {\n        \"MANAGER_API_URL\": \"http://127.0.0.1:55667/api2\",\n        \"MANAGER_API_KEY\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Claude Code</strong></summary>\n\nAdd via CLI:\n\n```bash\nclaude mcp add manager --env MANAGER_API_URL=http://127.0.0.1:55667/api2 --env MANAGER_API_KEY=your-token -- uvx manager-mcp\n```\n\nOr edit `~/.claude.json` / project MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"manager\": {\n      \"command\": \"uvx\",\n      \"args\": [\"manager-mcp\"],\n      \"env\": {\n        \"MANAGER_API_URL\": \"http://127.0.0.1:55667/api2\",\n        \"MANAGER_API_KEY\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>VS Code / GitHub Copilot</strong></summary>\n\nCreate [`.vscode/mcp.json`](.vscode/mcp.json) in the project root:\n\n```json\n{\n  \"servers\": {\n    \"manager\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"manager-mcp\"],\n      \"env\": {\n        \"MANAGER_API_URL\": \"http://127.0.0.1:55667/api2\",\n        \"MANAGER_API_KEY\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\nLocal editable:\n\n```json\n{\n  \"servers\": {\n    \"manager\": {\n      \"type\": \"stdio\",\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/manager-mcp\", \"manager-mcp\"],\n      \"env\": {\n        \"MANAGER_API_URL\": \"http://127.0.0.1:55667/api2\",\n        \"MANAGER_API_KEY\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\nReload the window. Open Copilot Chat and confirm the `manager` tools are available.\n\n</details>\n\n<details>\n<summary><strong>Windsurf</strong></summary>\n\nEdit `~/.codeium/windsurf/mcp_config.json` (macOS/Linux) or the Windsurf MCP settings UI:\n\n```json\n{\n  \"mcpServers\": {\n    \"manager\": {\n      \"command\": \"uvx\",\n      \"args\": [\"manager-mcp\"],\n      \"env\": {\n        \"MANAGER_API_URL\": \"http://127.0.0.1:55667/api2\",\n        \"MANAGER_API_KEY\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\nRestart Windsurf after saving.\n\n</details>\n\n<details>\n<summary><strong>Zed</strong></summary>\n\nAdd under `context_servers` in Zed `settings.json` (Agent Panel → settings also works):\n\n```json\n{\n  \"context_servers\": {\n    \"manager\": {\n      \"command\": \"uvx\",\n      \"args\": [\"manager-mcp\"],\n      \"env\": {\n        \"MANAGER_API_URL\": \"http://127.0.0.1:55667/api2\",\n        \"MANAGER_API_KEY\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Cline</strong></summary>\n\nEdit the Cline MCP settings file (`cline_mcp_settings.json` via the Cline MCP UI):\n\n```json\n{\n  \"mcpServers\": {\n    \"manager\": {\n      \"command\": \"uvx\",\n      \"args\": [\"manager-mcp\"],\n      \"env\": {\n        \"MANAGER_API_URL\": \"http://127.0.0.1:55667/api2\",\n        \"MANAGER_API_KEY\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Continue</strong></summary>\n\nIn `.continue/config.yaml`:\n\n```yaml\nmcpServers:\n  - name: manager\n    command: uvx\n    args:\n      - manager-mcp\n    env:\n      MANAGER_API_URL: http://127.0.0.1:55667/api2\n      MANAGER_API_KEY: your-token\n```\n\n</details>\n\n<details>\n<summary><strong>Generic / any stdio MCP host</strong></summary>\n\nAny host that can spawn a stdio MCP server:\n\n| Field | Value |\n|-------|-------|\n| Command | `uvx` |\n| Args | `manager-mcp` |\n| Env | `MANAGER_API_URL`, `MANAGER_API_KEY` (+ optional write scopes) |\n\n```bash\nuvx manager-mcp\n```\n\nDev from a clone: `uv run --directory /path/to/manager-mcp manager-mcp`.\n\n`npx` only runs npm packages. This is a Python package; use `uvx`.\n\n</details>\n\n## Environment\n\n| Variable | Required | Notes |\n|----------|----------|-------|\n| `MANAGER_API_URL` | yes | Opaque base URL (include `/api2` when needed) |\n| `MANAGER_API_KEY` | yes | Sent as `X-API-KEY`; never logged |\n| `MANAGER_MCP_WRITE_SCOPES` | no | Comma-separated domains for create/update. Empty = no writes. |\n| `MANAGER_MCP_DELETE_SCOPES` | no | Comma-separated domains for delete only. Never implied by WRITE_SCOPES. |\n\nValid scopes: `quotes`, `orders`, `parties`, `items`, `sales`, `purchases`, `banking`, `payroll`, `ledger`, `raw`. No wildcards (`*`, `all`).\n\n**Recommended** (covers most bookkeeping without 82 tools):\n\n```json\n\"MANAGER_MCP_WRITE_SCOPES\": \"banking,sales,parties\",\n\"MANAGER_MCP_DELETE_SCOPES\": \"sales,banking\"\n```\n\nDefault with no scopes: **10 tools**. All nine domain scopes plus every CRUD verb: up to **82 tools**. Use `raw` only when you need the full CRUD escape hatch.\n\nLegacy `MANAGER_MCP_ALLOW_WRITES` / `ALLOW_WRITES` / `MANAGER_MCP_WRITES` hard-fail if set. Use the scoped vars instead.\n\nSee [`.env.example`](.env.example). Prefer a secret manager for the API key in production configs.\n\n## Write scopes and task tools\n\nWhen a scope is listed in `MANAGER_MCP_WRITE_SCOPES`, the server registers **task tools** for that domain plus deprecated CRUD twins. `MANAGER_MCP_DELETE_SCOPES` enables `void_document` and `delete_*` per domain.\n\n### Task tools (preferred)\n\n| Tool | Scopes | Purpose |\n|------|--------|---------|\n| `create_customer`, `create_supplier` | parties | Single-resource party setup |\n| `issue_sales_invoice` | sales | Issue invoice with inline lines |\n| `issue_purchase_invoice` | purchases | Issue purchase invoice |\n| `issue_quote` | quotes | Issue sales or purchase quote |\n| `convert_quote_to_invoice` | quotes + sales | Convert quote to invoice |\n| `record_customer_payment` | banking | Receipt + invoice allocation |\n| `record_supplier_payment` | banking | Payment + invoice allocation |\n| `record_expense` | payroll and/or purchases | Expense claim or purchase invoice |\n| `transfer_between_accounts` | banking | Inter-account transfer |\n| `post_journal_entry` | ledger | Generic journal entry |\n| `void_document` | matching delete scope | Void by resource name + key |\n| `record_customer_deposit` | banking | Deposit before invoice exists |\n| `issue_deposit_invoice` | quotes | Deposit document (quote) |\n| `apply_deposit_to_invoice` | ledger | Apply deposit via journal |\n\nBodies for composite tools use Manager-native JSON where noted. Clone `get_record` templates; do not invent field names.\n\n### Deprecated CRUD (0.2.0, removed 0.3.0)\n\nPer-resource `create_*` / `update_*` / `delete_*` still register when their domain scope is enabled. Descriptions are prefixed `[DEPRECATED in 0.2.0; use task tools]` except `create_customer` / `create_supplier`. Set `raw` in `MANAGER_MCP_WRITE_SCOPES` to register CRUD without deprecation prefixes.\n\n| Scope | Resources (CRUD when enabled) |\n|-------|-------------------------------|\n| `quotes` | sales_quotes, purchase_quotes |\n| `orders` | sales_orders, purchase_orders |\n| `parties` | customers, suppliers |\n| `items` | inventory_items, non_inventory_items |\n| `sales` | sales_invoices, credit_notes, delivery_notes |\n| `purchases` | purchase_invoices, debit_notes, goods_receipts |\n| `banking` | receipts, payments, inter_account_transfers, bank_accounts |\n| `payroll` | employees, payslips, expense_claims |\n| `ledger` | journal_entries, depreciation_entries, amortization_entries |\n\nExample with recommended scopes only:\n\n```json\n\"MANAGER_MCP_WRITE_SCOPES\": \"banking,sales,parties\",\n\"MANAGER_MCP_DELETE_SCOPES\": \"sales\"\n```\n\n**Denylist (always blocked):** access-token forms, chart-of-accounts / `*-account-form` (except bank-or-cash), bank reconciliation, customer portal, starting balances, tax codes, exchange rates, currencies, custom fields/buttons, themes, email templates/settings.\n\n## Customer deposit workflow\n\nA **deposit is not revenue**. Money received before delivery must not be booked to an income account. Confirm tax/VAT treatment with your accountant.\n\n1. Ensure a **Customer deposits** bank/cash account exists in Manager (Settings → Bank and Cash Accounts).\n2. `record_customer_deposit` - posts cash to that account. If the account is missing, the tool returns `precondition_failed` with exact setup steps (Option A: guide only, no auto-create).\n3. `issue_deposit_invoice` (optional) - quote styled as a deposit document for the customer.\n4. `issue_sales_invoice` when the real invoice is raised.\n5. `apply_deposit_to_invoice` - journal entry moving deposit balance to the invoice (clone an existing journal via `get_record`).\n\nRequired scopes: `banking`, `quotes` (deposit doc), `ledger` (apply), `sales` (final invoice via MCP).\n\n## Migration from 0.1.x\n\n- **0.2.0**: Task tools added; CRUD tools deprecated but still present under scopes.\n- **0.3.0**: CRUD tools removed (except `create_customer` / `create_supplier`). Use task tools or `raw` scope.\n- Update `MANAGER_MCP_WRITE_SCOPES` to the recommended narrow set above instead of enabling all domains.\n\n## Tools\n\n### Read tools\n\n| Tool | Purpose | Period (`from_date` / `to_date`) |\n|------|---------|----------------------------------|\n| `list_resources` | Discovery; reports `read_only` + live write/delete scopes | n/a |\n| `list_records` | Search/page a curated collection | n/a |\n| `get_record` | Fetch one record via `{path}-form/{key}` | n/a |\n| `aged_receivables` | Outstanding / aging customers | Accepted; may be unsupported on this view |\n| `aged_payables` | Aging suppliers | Accepted; may be unsupported on this view |\n| `bank_balances` | Bank/cash **balances snapshot** | Accepted; may be unsupported on this view |\n| `trial_balance` | Trial balance | Forwarded as `fromDate` / `toDate` |\n| `profit_and_loss` | P&L | Forwarded as `fromDate` / `toDate` |\n| `balance_sheet` | Balance sheet | Forwarded as `fromDate` / `toDate` |\n| `tax_summary` | Tax summary | Accepted; may be unsupported on this view |\n\nCollections for `list_records` / `get_record`: `customers`, `suppliers`, `sales_invoices`, `purchase_invoices`, `chart_of_accounts`, `bank_accounts`.\n\n`chart_of_accounts` is list/search only (no single-form GET).\n\n**Bank dual path (intentional):** `bank_balances` answers “what are my balances?”; `list_records` / `get_record` on `bank_accounts` answers “find account X and show detail.”\n\n### Write tools (deprecated)\n\nRegistered only for resources in enabled scopes. Prefer task tools above.\n\n| Pattern | Requires | Notes |\n|---------|----------|-------|\n| `create_{stem}` | write scope | Deprecated in 0.2.0 |\n| `update_{stem}` | write scope | Deprecated in 0.2.0 |\n| `delete_{stem}` | delete scope | Deprecated in 0.2.0; use `void_document` |\n\n## Agent Skill\n\nCompanion skill: [`skills/manager-accounting/SKILL.md`](skills/manager-accounting/SKILL.md).\n\nThe Cursor plugin discovers this skill from `skills/`. Without the plugin, copy or symlink that folder into your agent skills path. It tells the model to call `list_resources` first, verify after writes, and which report tools to prefer.\n\n## Development\n\n```bash\nuv sync --extra dev\nuv run manager-mcp\n```\n\nOffline tests only (respx). No live Manager required:\n\n```bash\nuv run ruff check src tests\nuv run pytest\n```\n\nGitHub Actions matrix: Python 3.10 and 3.12.\n\n## Caveats\n\n- One process ↔ one `MANAGER_API_URL`. Multi-instance routing is out of scope.\n- Multi-business disambiguation on a shared host is **unverified**. Do not claim multi-business support until validated against a live multi-business setup.\n- Vendored `src/manager_mcp/spec/api2.json` is provenance only; runtime always hits the live URL.\n- ChatGPT Apps need a hosted HTTP MCP endpoint. This package is stdio-only.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 18782,
  "sha": "a669cecbfb2d9b508b857ee0dbd332d62c8b72c6b3104b94cb35dd37a90d353d",
  "repo_slug": "flumpiey/manager-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_flumpiey_manager_mcp_309da1d6/readme"
}