Skip to main content
Glama
Sign In
MYOB Codex MCP

MYOB Codex MCP

by jaeko44
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

MYOB Codex MCP

Codex-safe MCP server for MYOB Business / AccountRight cloud.

The server is designed for two modes at the same time:

  • Read-only tools are available by default.

  • Mutating MYOB actions are available, but every create/update/delete/post/payment/banking/journal action is prepared first, then requires explicit accountant/user approval, then commits with a payload-bound approval token.

This repo is a clean-room implementation. The public fixxdigital/myob-mcp-server project informed endpoint coverage and OAuth shape, but source code is not copied because that repo did not expose a license when this project was created. The CData MYOB MCP repo informed the metadata/discovery pattern.

Status

Current implementation:

  • Python package and stdio MCP server.

  • MYOB OAuth URL, token exchange, refresh, logout, and encrypted multi-business token persistence.

  • MYOB API client with headers, businessId path selection, pagination, 401 refresh, 429 backoff, and unsafe mutation retry protection.

  • Read tools for accounts, tax codes, jobs, contacts, invoices, bills, payments, banking, inventory items, journals, and raw GET.

  • Write preparation tools for raw API mutations and common accounting workflows.

  • Approval broker with pending operations, approval phrase, signed approval token, payload hash binding, expiry, once-only commit, and JSONL audit logging.

  • CLI approval helper.

  • CI, tests, and docs.

Live MYOB sandbox acceptance requires real MYOB developer credentials and a sandbox/company file. Until credentials are provided, CI uses unit and contract tests with mocked MYOB behavior.

Related MCP server: MYOB AccountRight

Install

cd C:\Users\jON\myob-codex-mcp
uv venv
uv pip install -e ".[dev]"
uv run pytest

Configure

Create %APPDATA%\myob-codex-mcp\config.toml:

[myob]
client_id = "${MYOB_CLIENT_ID}"
client_secret = "${MYOB_CLIENT_SECRET}"
redirect_uri = "http://127.0.0.1:33333/callback"
default_business_id = ""

[auth]
scopes = [
  "sme-company-file",
  "sme-general-ledger",
  "sme-sales",
  "sme-purchases",
  "sme-inventory",
  "sme-payroll",
  "sme-reports",
  "sme-time-billing",
  "sme-banking",
  "sme-contacts-customer",
  "sme-contacts-supplier",
  "sme-contacts-employee",
  "offline_access"
]

[permissions]
allow_writes = true
approval_mode = "local_approval"
approval_ttl_seconds = 900
pending_ttl_seconds = 3600

Set secrets outside the repo:

$env:MYOB_CLIENT_ID = "..."
$env:MYOB_CLIENT_SECRET = "..."

Codex MCP Config

Codex can run this server as a local stdio MCP server:

[mcp_servers.myob]
command = "C:\\Users\\jON\\myob-codex-mcp\\.venv\\Scripts\\myob-codex-mcp.exe"

[mcp_servers.myob.env]
MYOB_CLIENT_ID = "..."
MYOB_CLIENT_SECRET = "..."
MYOB_CODEX_MCP_CONFIG = "C:\\Users\\jON\\AppData\\Roaming\\myob-codex-mcp\\config.toml"

You can append a starter config with:

.\scripts\codex-register.ps1

First Run

In Codex, call:

myob_oauth_authorize_business

If the localhost callback cannot be reached:

myob_oauth_authorize_business(manual=true)
myob_oauth_exchange_redirect_url(redirect_url="https://app.example/callback?code=...&businessId=...")

This repo also includes a dependency-free static callback helper in site/. It can be deployed at https://app.professionalaccounting.com.au so accountants can copy the exact Codex/MCP exchange instruction after MYOB redirects back. See docs/callback-site.md.

Repeat this once for each MYOB business/company file that an accountant administers. The same MYOB Developer App key/secret can be reused, but each business must grant consent separately. Authorised businesses can then be listed and selected:

myob_business_list_authorized
myob_business_set_default(business_id="...")
myob_business_remove_authorization(business_id="...")

Most read tools accept business_id, for example:

myob_invoice_list(business_id="...")
myob_raw_get(path="/GeneralLedger/Account", business_id="...")

Approval Flow

Writes are two-phase:

  1. Prepare the operation.

  2. Approve it.

  3. Commit it.

Example:

myob_invoice_prepare_create(json_body={...}, layout="Service")
myob_approval_approve(operation_id="op_...", approver="Jane Accountant", approval_phrase="APPROVE op_...")
myob_commit_operation(operation_id="op_...", approval_token="...")

The commit fails if:

  • the operation was not approved;

  • the approval token expired;

  • the payload changed after approval;

  • the operation was already committed;

  • write tools are disabled;

  • MYOB rejects the request.

Full Access Model

Named tools cover normal accounting workflows. For endpoint coverage beyond named tools, use:

myob_raw_get(path="/Some/Endpoint", params={...})
myob_raw_prepare_mutation(method="POST", path="/Some/Endpoint", json_body={...}, summary="...")
myob_raw_commit_mutation(operation_id="op_...", approval_token="...")

That keeps the MCP from artificially limiting MYOB access while still requiring human approval before mutation.

Security

  • Logs go to stderr so stdout remains MCP JSON-RPC.

  • OAuth tokens are encrypted at rest.

  • Tokens are stored per MYOB businessId.

  • Approval tokens are HMAC-signed and short-lived.

  • Pending operation payloads are hash-bound to approvals.

  • Audit logs redact secrets.

  • Mutating timeout retries are blocked unless an idempotency key is available.

See docs/threat-model.md.

Moving auth state to another machine

python scripts/auth_bundle.py export <bundle-file>   # on the machine that holds the auth
python scripts/auth_bundle.py import <bundle-file>   # on the new machine, after installing the repo

The bundle is sealed with a passphrase (scrypt + Fernet) and contains the tokens, config.toml and the token encryption key. Send the passphrase by a different channel from the file. Two machines should not both refresh the same tokens; re-consent on the new machine if MYOB rotates refresh tokens.

Available Tools

63 tools
myob_account_getB

Get a chart-of-accounts record by UID.

Inputs: uid (required), business_id.

myob_account_listC

List chart of accounts.

Inputs: top, filter, business_id. Returns: object

myob_approval_approveB

Approve a prepared MYOB write. The approval_phrase must be exactly 'APPROVE <operation_id>'.

Inputs: approver (required), operation_id (required), approval_phrase (required), reason.

myob_approval_denyC

Deny a prepared or approved MYOB write operation.

Inputs: denied_by (required), operation_id (required), reason.

myob_approval_getB

Get the full approval preview for a MYOB operation.

Inputs: operation_id (required).

myob_approval_list_pendingA

List pending or approved MYOB operations awaiting user/accountant action.

Inputs: no named parameters.

myob_attachment_prepare_uploadA

Prepare attachment upload. content_base64 is stored in the pending payload until approved.

Inputs: file_name (required), parent_path (required), content_base64 (required), business_id, +1 more. Returns: object

myob_auth_statusA

Show MYOB OAuth authentication, token, and selected business status.

Inputs: no named parameters.

myob_bank_account_listC

List bank accounts.

Inputs: top, business_id. Returns: object

myob_bill_getA

Get bill by UID. If layout is supplied, reads the layout-specific detail endpoint.

Inputs: uid (required), layout, business_id.

myob_bill_listC

List purchase bills.

Inputs: top, filter, business_id. Returns: object

myob_bill_prepare_createB

Prepare creation of a purchase bill. Requires approval before commit.

Inputs: json_body (required), layout, business_id. Returns: object

myob_bill_prepare_updateA

Prepare update of a purchase bill. Requires approval before commit.

Inputs: uid (required), json_body (required), layout, business_id. Returns: object

myob_business_list_authorizedA

List MYOB businesses/company files already authorised on this machine.

Inputs: no named parameters.

myob_business_remove_authorizationA

Remove locally stored OAuth tokens for one MYOB business/company file.

Inputs: business_id (required).

myob_business_set_defaultB

Set the default MYOB business/company file for future tool calls.

Inputs: business_id (required).

myob_commit_operationA

Commit any approved MYOB operation. This mutates MYOB and requires a valid approval token.

Inputs: operation_id (required), approval_token (required).

myob_company_get_contextB

Return the selected MYOB business/company file context.

Inputs: no named parameters.

myob_company_list_filesB

Try to list accessible company files. New MYOB OAuth flows may require businessId from consent instead.

Inputs: no named parameters.

myob_contact_getC

Get any contact by UID.

Inputs: uid (required), business_id.

myob_customer_listC

List customers.

Inputs: top, filter, business_id. Returns: object

myob_customer_payment_listC

List customer payments.

Inputs: top, filter, business_id. Returns: object

myob_customer_payment_prepare_recordC

Prepare recording a customer payment. High-risk approval required.

Inputs: json_body (required), business_id. Returns: object

myob_customer_prepare_createA

Prepare creation of a customer contact. Requires approval before commit.

Inputs: json_body (required), business_id. Returns: object

myob_customer_prepare_updateB

Prepare update of a customer contact. Requires approval before commit.

Inputs: uid (required), json_body (required), business_id. Returns: object

myob_employee_listC

List employees.

Inputs: top, filter, business_id. Returns: object

myob_entity_getA

Get one MYOB record by entity and UID. layout is needed for some invoice/bill/order details.

Inputs: uid (required), entity (required), layout, business_id.

myob_entity_listC

List records for a supported MYOB entity using the endpoint registry.

Inputs: entity (required), top, filter, orderby, +2 more. Returns: object

myob_entity_prepare_createD

Prepare create for a supported entity using the endpoint registry.

Inputs: entity (required), json_body (required), layout, summary, +1 more. Returns: object

myob_entity_prepare_updateD

Prepare update for a supported entity using the endpoint registry.

Inputs: uid (required), entity (required), json_body (required), layout, +2 more. Returns: object

myob_inventory_item_listC

List inventory items.

Inputs: top, filter, business_id. Returns: object

myob_inventory_item_prepare_createB

Prepare inventory item creation. Requires approval before commit.

Inputs: json_body (required), business_id. Returns: object

myob_invoice_getA

Get invoice by UID. If layout is supplied, reads the layout-specific detail endpoint.

Inputs: uid (required), layout, business_id.

myob_invoice_listC

List sales invoices.

Inputs: top, filter, business_id. Returns: object

myob_invoice_prepare_createB

Prepare creation of a sales invoice. Requires approval before commit.

Inputs: json_body (required), layout, business_id. Returns: object

myob_invoice_prepare_deleteA

Prepare deletion/void-style removal of a sales invoice where MYOB permits it. Critical approval required.

Inputs: uid (required), layout, business_id. Returns: object

myob_invoice_prepare_updateB

Prepare update of a sales invoice. Requires approval before commit.

Inputs: uid (required), json_body (required), layout, business_id. Returns: object

myob_job_listC

List jobs.

Inputs: top, business_id. Returns: object

myob_journal_listC

List general journal records.

Inputs: top, filter, business_id. Returns: object

myob_journal_prepare_createC

Prepare general journal creation. High-risk approval required.

Inputs: json_body (required), business_id. Returns: object

myob_metadata_get_entity_schemaC

Return known MYOB endpoint paths and write flow for an entity.

Inputs: entity (required).

myob_metadata_get_tool_catalogA

Return a machine-readable catalog of major MCP tools and mutation policy.

Inputs: no named parameters.

myob_metadata_list_domainsA

List MYOB entity domains supported by this MCP server.

Inputs: no named parameters.

myob_oauth_authorizeD

Alias for myob_oauth_authorize_business.

Inputs: manual, open_browser.

myob_oauth_authorize_businessB

Start MYOB OAuth consent for one business/company file. Repeat once per business.

Inputs: manual, open_browser.

myob_oauth_exchange_codeB

Manually exchange an OAuth code for one MYOB business and store its encrypted tokens.

Inputs: code (required), business_id (required), state.

myob_oauth_exchange_redirect_urlA

Exchange the full MYOB OAuth redirected URL containing code, businessId, and state.

Inputs: redirect_url (required).

myob_oauth_logoutA

Clear all stored MYOB OAuth tokens from this machine.

Inputs: no named parameters.

myob_oauth_refreshA

Refresh a stored MYOB OAuth access token for one business or the default business.

Inputs: business_id.

myob_raw_commit_mutationA

Commit an approved raw MYOB mutation. This mutates MYOB and requires a valid approval token.

Inputs: operation_id (required), approval_token (required).

myob_raw_getC

Read any MYOB Business API endpoint with GET. This tool is read-only.

Inputs: path (required), params, business_id.

myob_raw_prepare_mutationA

Prepare any MYOB POST/PUT/PATCH/DELETE request. This does not call MYOB until approved and committed.

Inputs: path (required), method (required), params, summary, +3 more. Returns: object

myob_receive_money_listC

List receive-money transactions.

Inputs: top, filter, business_id. Returns: object

myob_receive_money_prepare_createC

Prepare receive-money transaction creation. High-risk approval required.

Inputs: json_body (required), business_id. Returns: object

myob_sales_order_prepare_createB

Prepare creation of a sales order. Requires approval before commit.

Inputs: json_body (required), layout, business_id. Returns: object

myob_spend_money_listC

List spend-money transactions.

Inputs: top, filter, business_id. Returns: object

myob_spend_money_prepare_createC

Prepare spend-money transaction creation. High-risk approval required.

Inputs: json_body (required), business_id. Returns: object

myob_supplier_listC

List suppliers.

Inputs: top, filter, business_id. Returns: object

myob_supplier_payment_listC

List supplier payments.

Inputs: top, filter, business_id. Returns: object

myob_supplier_payment_prepare_recordC

Prepare recording a supplier payment. High-risk approval required.

Inputs: json_body (required), business_id. Returns: object

myob_supplier_prepare_createA

Prepare creation of a supplier contact. Requires approval before commit.

Inputs: json_body (required), business_id. Returns: object

myob_supplier_prepare_updateC

Prepare update of a supplier contact. Requires approval before commit.

Inputs: uid (required), json_body (required), business_id. Returns: object

myob_tax_code_listC

List tax codes.

Inputs: top, business_id. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    C2.6/5.0

    Scored across 63 tools

    Disambiguation3/5

    Most tools are clearly separated by entity (invoice, bill, customer), but there is overlap between generic raw/entity tools and entity-specific tools (e.g., myob_entity_list vs myob_invoice_list). The alias myob_oauth_authorize duplicates myob_oauth_authorize_business, and myob_raw_commit_mutation vs myob_commit_operation vs myob_approval_approve creates boundary confusion.

    Naming Consistency4/5

    The overwhelming pattern is myob_<resource>_<action> (e.g., account_list, invoice_get), with only a few deviations like myob_commit_operation (missing resource prefix) and myob_oauth_authorize_business (compound action). Overall, the naming is predictable and readable.

    Tool Count2/5

    With 63 tools, this is far above the typical 3-15 well-scoped range. While the MYOB domain is broad, the number of tools creates a heavy decision surface for agents, and many are list-only variants that could be consolidated.

    Completeness4/5

    The toolset covers a wide range of MYOB entities (accounts, customers, suppliers, invoices, bills, payments, inventory, jobs, etc.) with list/get operations, and prepare/commit flows for core mutations. The generic raw endpoint tools and metadata tools fill most gaps, though some mutations (e.g., employee, job) are only possible via the raw layer.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • MYOB AccountRight

      CDataSoftware
      A
      license
      Not graded
      quality
      D
      maintenance
      This read-only MCP Server allows you to connect to MYOB AccountRight data from Claude Desktop through CData JDBC Drivers. Free (beta) read/write servers available at https://www.cdata.com/solutions/mcp
      4
      MIT

    • Exact Online

      iwebdevnl
      A
      license
      Not graded
      quality
      D
      maintenance
      Hosted MCP server for Exact Online. Ask questions, pull reports, and prepare bookings you approve first.
      MIT

    • manager-mcp

      flumpiey
      A
      license
      B
      quality
      C
      maintenance
      Read-only MCP server for self-hosted Manager.io bookkeeping, providing curated GET tools to access accounting data like invoices, balances, and reports.
      10
      32 PyPI
      1
      MIT