Onexur Manager MCP

Onexur Manager MCP

An MCP (Model Context Protocol) server that connects AI assistants such as Claude and ChatGPT to a Manager accounting instance. It exposes Manager's data and operations as a set of scoped tools. The default is read-only, with reporting, diagnostic and reconciliation tools available out of the box and every write capability behind explicit configuration.

This project began as a fork of manager-mcp 0.2.6. See Attribution below.

1. Project description

Onexur Manager MCP lets an AI assistant read and, where explicitly permitted, act on a Manager accounting instance through a structured tool interface rather than free-form API calls. The server enforces a tiered permission model so that read access and write access are each opted into separately, and delete access is opted into separately again.

Typical uses:

• Ask an assistant to explain a balance, find unpaid invoices, or summarise account activity.
• Run reconciliation and diagnostic checks (duplicate transactions, unallocated payments, broken invoice references, suspense account candidates) without writing a script.
• Rebuild a trial balance, profit and loss or aged balances as at a past date from Manager's ledger, clearly labelled as a reconstruction and not an official report.
• Propose and, after review, apply corrections to specific transaction types, always through an explicit propose then apply pattern rather than a direct write.

Nothing that changes Manager is registered by default. Every write request is also checked against a permanent denylist before any scope is consulted (see Configuration).

2. Installation

The package is named mcp-manager.io, the Python module is manager_mcp, and the commands are manager-mcp and manager-mcp-dev. It requires Python 3.10 or later and uv.

Until the first release is published to PyPI, run it from a clone:

git clone https://github.com/onexurOSS/mcp-manager.io.git

cd mcp-manager.io uv sync uv run manager-mcp

After publication, no clone is needed:

uvx --from mcp-manager.io manager-mcp

The server speaks MCP over stdio. To use it from a client, configure the client to run one of the commands above with your Manager connection details as environment variables, for example:

{

"mcpServers": { "manager": { "command": "uvx", "args": ["--from", "mcp-manager.io", "manager-mcp"], "env": { "MANAGER_API_URL": "http://127.0.0.1:55667/api2", "MANAGER_API_KEY": "your-access-token" } } } }

Client integrations in this repository:

• mcpb/ holds the manifest for a Claude Desktop extension bundle. Built bundles are not committed. The manifest runs the published mcp-manager.io package through uv, so it works once the package is published.
• .cursor-plugin/plugin.json is a Cursor plugin manifest.
• For other clients, such as a .cursor/mcp.json or .vscode/mcp.json entry in your own project, use the pattern above.

ChatGPT Apps need a hosted HTTP endpoint. This package is stdio only.

3. Configuration

One process talks to one Manager instance, configured through environment variables:

The older MANAGER_MCP_ALLOW_WRITES, ALLOW_WRITES and MANAGER_MCP_WRITES variables are rejected with an error that points to the two scope variables above.

Never commit your API key. Keep it in the environment of the MCP client or in a private env file.

Transports

stdio is the default and the only transport a registry-launched (uvx) process uses. HTTP is additive and opt-in for self-hosted deployments that need this server reachable over a network rather than only through local stdio pipes:

HTTP mode exposes the exact same tools, the exact same scope/policy enforcement, and the exact same single-Manager-instance-per-process model as stdio -- only the transport changes. It does not add multi-tenancy or multiple Manager instances per process; that belongs in a separate gateway service in front of this one.

Security note: MANAGER_MCP_HTTP_AUTH_TOKEN is a single shared secret for the whole process, checked at the transport layer -- it is not per-caller identity, OAuth, or a replacement for a real auth boundary. When it is unset, HTTP mode has no transport-level authentication at all: any client that can reach the configured host:port can call every tool this process exposes, subject only to the scope/denylist policy above (which governs what can be done, not who may connect). That is only safe when network placement -- loopback binding, a private Docker network, a VPN, or a gateway/reverse proxy that performs the real authentication -- is genuinely the sole access control. The server prints a warning to stderr at startup when running in HTTP mode with no token configured, rather than staying silent about it. Given this server can expose real bookkeeping data (and, depending on configured scopes, write/delete access to it), operators are strongly encouraged to set the token, place the server behind a gateway, or both.

Permission scopes

Valid scopes are quotes, orders, parties, items, sales, purchases, banking, payroll and ledger, plus raw, an escape hatch that enables the full create and update (or delete) set for every domain. A recommended starting point for day-to-day bookkeeping is banking,sales,parties.

With no scopes set, 30 read-only tools are registered. Enabling a scope registers only the tools for that domain. Scopes are additive and independent, and unknown scope names are refused at startup. With every write and delete scope enabled, up to 126 tools are registered.

Every request that would change Manager passes a policy check first. Requests to paths such as access tokens, the chart of accounts, tax codes, exchange rates, starting balances, bank reconciliation, custom fields, email settings and the customer portal are permanently denied, whatever scopes are enabled.

4. Tool descriptions

Read tools (registered by default, 30 in total)

• Discovery and raw access: list_resources, list_records, get_record, get_fixed_asset and get_server_info (server identity, process, git state, registered tools and active scopes).
• Legacy report shortcuts: aged_receivables, aged_payables, bank_balances, trial_balance, profit_and_loss, balance_sheet and tax_summary. These return Manager's current state or raw feeds and are not finished reports (see Reporting limitations).
• Reporting layer (reporting.py): manager_report_catalogue, get_report_definition, ledger_transactions, reconstructed_trial_balance, reconstructed_profit_and_loss, reconstructed_aged_receivables and reconstructed_aged_payables.
• Diagnostics (diagnostics.py): find_records, find_broken_invoice_references, find_unallocated_transactions, find_duplicate_transactions, verify_invoice_balance, account_ledger, bank_activity, find_suspense_candidate_accounts and general_ledger_summary.
• Reconciliation (reconciliation.py): reconcile_period.
• list_incomplete_reconstructions (corrections.py): invoice-reconstruction attempts that started but have not completed, from the local audit log only.

Write tools (registered only when the matching scope is enabled)

• Task tools (task_tools.py) shaped around an intent, for example issue_sales_invoice, issue_purchase_invoice, record_customer_payment, record_supplier_payment, record_expense, transfer_between_accounts and post_journal_entry. These are the recommended write path.
• Per-resource create_* and update_* tools for each enabled scope, and delete_* tools for each enabled delete scope. create_fixed_asset and update_fixed_asset (fixed_assets.py) need the ledger scope.
• Corrections (corrections.py): propose_correction and apply_correction, propose_*_reconstruction and apply_*_reconstruction for purchase and sales invoices, reallocate_payment_line and reallocate_receipt_line, and snapshot_and_void, which is preferred over the plain void_document tool. Nothing here writes without a separate apply step after a proposal, and each corrective write is recorded in the audit log.

Descriptions and schemas for every registered tool are available from your MCP client, and get_server_info reports which are active.

5. Reporting limitations

Manager's API does not return finished reports. The report view routes are application only and answer HTTP 401 to an API key, and this project neither calls nor imitates them. The reporting tools work from what the API does return, and label what they return. The full guide is docs/reporting.md.

• Reconstructions are never authoritative. reconstructed_trial_balance, reconstructed_profit_and_loss, reconstructed_aged_receivables and reconstructed_aged_payables are calculated by this server from Manager's account level ledger. Each result carries authoritative: false and official_manager_report: false, with its source, calculation method, as-at date and ledger completeness. A match with a figure in Manager does not make a reconstruction official.
• Reconstructed ageing can differ from Manager's. Ageing here uses transaction dates and applies payments oldest first, whereas Manager uses due dates and actual allocations, so bucket splits can differ. Party totals are checked only against the control account total.
• Current state tools reject dates. aged_receivables, aged_payables, bank_balances and tax_summary show balances as they are today. If you pass a date or period they refuse the request, and they never return today's figures for a past date.
• Dates on the ledger are filtered here. Manager ignores date parameters on its /transactions ledger feed, so the server fetches the complete ledger and filters it itself. Results are never silently truncated. Paged results report totals and a next position, and feeds report whether they are complete.
• Not available from the API: Manager's own group and subtotal layout, invoice due dates and allocations as at a past date, VAT returns, and finished report output.

Do not treat any reporting tool as a substitute for Manager's own reports where precision matters