LedgerHQ
Guides

Codex Plugin & Claude MCP

Install the LedgerHQ Codex plugin, connect Claude through LedgerHQ's remote MCP server, or choose direct API access for trusted staff agents.

LedgerHQ supports three agent setup paths. AI agents should read For AI Agents before choosing tools or browsing the API reference.

If you use Codex, install the LedgerHQ Codex plugin. The plugin is the recommended Codex experience because it includes the LedgerHQ skills, packaged setup, and token-backed MCP configuration Codex needs to reach your LedgerHQ books through LEDGERHQ_MCP_TOKEN.

If you use Claude, connect Claude to the LedgerHQ remote MCP server. Claude does not install the LedgerHQ Codex plugin; it connects to the same LedgerHQ bookkeeping tool surface through MCP and OAuth.

If you use a trusted staff agent that wants direct HTTP access, use the Direct Agent API. That path is for admin and support operations with a managed bearer key from /admin/agent-access, not normal customer bookkeeping OAuth.

Codex: Install The LedgerHQ Plugin

For Codex, the important thing is the plugin. The plugin bundle installs a LedgerHQ entry into Codex, registers the local plugin marketplace, configures the bundled ledgerhq MCP server to read LEDGERHQ_MCP_TOKEN, and gives Codex the LedgerHQ bookkeeping skills that make the tool surface easier to use.

In LedgerHQ, create a Codex connection token from Profile > API and MCP. Then use this three-step flow:

1. Copy the setup message below and send it to Codex.
2. When Codex opens the LedgerHQ token file, paste this token into that file — not into chat. Save and close the file.
3. Return to Codex and say: Done.

Safe setup message:

Connect LedgerHQ using the official instructions at https://ledgerhq.pro/docs/guides/for-ai-agents. Detect this computer's platform, open the local LedgerHQ token file, and never ask me to paste the token into chat.

The installer stores the token in macOS Keychain or the Windows user environment, refreshes the LedgerHQ plugin, and reports whether Codex needs one full restart. If the connection later stops working, ask Codex:

Reconnect LedgerHQ.

Advanced Manual Setup

macOS commands:

curl -fsSL https://ledgerhq.pro/setup-ledgerhq-mcp-token.sh | bash -s open
curl -fsSL https://ledgerhq.pro/setup-ledgerhq-mcp-token.sh | bash -s install
curl -fsSL https://ledgerhq.pro/setup-ledgerhq-mcp-token.sh | bash -s status
curl -fsSL https://ledgerhq.pro/setup-ledgerhq-mcp-token.sh | bash -s repair

Windows PowerShell commands:

irm https://ledgerhq.pro/setup-ledgerhq-mcp-token.ps1 | iex
irm https://ledgerhq.pro/install-ledgerhq-mcp-token.ps1 | iex
& ([scriptblock]::Create((irm "https://ledgerhq.pro/setup-ledgerhq-mcp-token.ps1"))) -Mode status
& ([scriptblock]::Create((irm "https://ledgerhq.pro/setup-ledgerhq-mcp-token.ps1"))) -Mode repair

After installation, start a Codex message with @LedgerHQ, then ask for the bookkeeping work you want done.

Examples:

  • @LedgerHQ list my companies
  • @LedgerHQ show this month's profit and loss
  • @LedgerHQ help me reconcile bank activity
  • @LedgerHQ create a report export

Plugin-Only Install

macOS/Linux:

curl -fsSL https://ledgerhq.pro/install-codex-mcp.sh | bash

Windows PowerShell:

irm https://ledgerhq.pro/install-codex-plugin.ps1 | iex

Manual Codex Plugin Setup

Use the manual path if the one-line installer is unavailable or your machine needs a more explicit setup.

macOS/Linux:

mkdir -p "$HOME/.ledgerhq/codex-plugin"
curl -fsSL https://ledgerhq.pro/codex-plugin/ledgerhq-codex-plugin.tar.gz | tar -xz -C "$HOME/.ledgerhq/codex-plugin"
codex plugin marketplace add "$HOME/.ledgerhq/codex-plugin"
codex plugin add ledgerhq@ledgerhq-local
codex plugin list
codex mcp list

Windows PowerShell:

$root = Join-Path $HOME ".ledgerhq/codex-plugin"
New-Item -ItemType Directory -Force -Path $root | Out-Null
Invoke-WebRequest -Uri "https://ledgerhq.pro/codex-plugin/ledgerhq-codex-plugin.tar.gz" -OutFile "$env:TEMP/ledgerhq-codex-plugin.tar.gz" -UseBasicParsing
tar.exe -xzf "$env:TEMP/ledgerhq-codex-plugin.tar.gz" -C $root
codex plugin marketplace add $root
codex plugin add ledgerhq@ledgerhq-local
codex plugin list
codex mcp list

Codex setup does not ask you to paste MCP agent tokens, OAuth tokens, API keys, Plaid credentials, Stripe secrets, QBO credentials, bank credentials, or database URLs into chat. The local setup file is temporary and is deleted after the token is installed. OAuth remains available as an interactive fallback only after explicit user approval.

When auth is not healthy, LedgerHQ returns deterministic recovery fields such as next_action, auth_source_attempted, env_var_name, setup_url, required_scope, and company_access. Codex agents should follow those fields instead of trying browser OAuth workarounds.

Claude: Connect The Remote MCP Server

Claude connects directly to LedgerHQ's remote MCP endpoint:

https://ledgerhq.pro/api/mcp

Use the Claude path for Claude Code, Claude Desktop, claude.ai, or Cowork. This does not install the Codex plugin. It gives Claude access to the same approved LedgerHQ bookkeeping tools through MCP and OAuth.

Claude Code Fast Install

curl -fsSL https://ledgerhq.pro/install-claude-mcp.sh | bash

Claude Code Manual Install

claude mcp add --transport http --scope user ledgerhq https://ledgerhq.pro/api/mcp

Then run claude, type /mcp, choose ledgerhq, and sign in when the browser opens.

Claude.ai, Claude Desktop, Or Cowork

Open Claude's connector settings, choose Add custom connector, and paste the LedgerHQ MCP endpoint:

https://ledgerhq.pro/api/mcp

Use the same LedgerHQ host your team signs into.

How The Connection Works

Codex MCP access should use managed LedgerHQ MCP agent tokens stored in LEDGERHQ_MCP_TOKEN. These tokens are long-lived, revocable, scoped to bundled MCP capabilities, and can be limited to selected companies. Claude and other interactive MCP clients can still use OAuth 2.1 with PKCE. OAuth access tokens are intentionally short-lived at 1 hour; refresh tokens rotate and last 180 days.

OAuth remains available as an interactive fallback only after explicit user approval.

Both auth paths produce the same MCP tool context. Tools are scoped to the anchor/default organization and use direct database-backed services rather than HTTP self-calls. Company requests can be rescoped with organizationId, subject to the token's company allowlist and the actor's live firm access.

Direct Agent API access is separate. It uses a staff-admin-managed bearer key, starts at /api/v1/admin-agent/capabilities, and then calls supported /api/v1/admin/* routes over HTTP.

Current Tool Coverage

The generated inventory exposes the MCP tools registered through lib/mcp/tools/index.ts. Tool files for hidden or future app modules may remain in the repository, but only registered files are part of the live MCP surface. The current generated surface is 292 MCP tools across the registered tool files imported by lib/mcp/tools/index.ts.

Organization

  • connection_status
  • get_organization
  • list_accessible_organizations
  • list_firm_clients
  • create_client

Accounts

  • list_accounts
  • get_account
  • create_account
  • update_account
  • delete_account

Journal Entries

  • list_entries
  • get_entry
  • create_entry
  • post_entry
  • void_entry
  • create_journal_entry
  • create_scheduled_journal_entry
  • list_scheduled_journal_entries
  • update_scheduled_journal_entry
  • delete_scheduled_journal_entry
  • post_due_scheduled_journal_entries

Posting Resources

  • create_purchase
  • create_deposit
  • create_transfer
  • create_bill_payment
  • create_journal_entry

Banking Follow-Through

  • list_bank_accounts
  • get_bank_account
  • list_bank_statements
  • get_bank_statement_data
  • get_bank_statement_download_url
  • list_bank_transactions
  • get_bank_transaction
  • categorize_bank_transaction
  • reclassify_bank_transaction
  • reconcile_bank_transaction
  • exclude_bank_transaction
  • get_bank_reconciliation_status
  • prepare_bank_reconciliation
  • start_bank_reconciliation
  • update_bank_reconciliation
  • cancel_bank_reconciliation
  • finish_bank_reconciliation
  • create_reconciliation_entry

Statement Coverage

  • list_statement_coverage_policies
  • set_statement_coverage_policy
  • list_statement_coverage_gaps
  • list_statement_coverage_recommendations
  • resolve_statement_coverage_recommendation
  • request_statement_for_period
  • upload_bank_statement
  • create_bank_statement_upload
  • waive_statement_coverage_period

Reports

  • trial_balance
  • balance_sheet
  • profit_and_loss
  • get_report_export_url
  • get_report_pdf
  • generate_financial_packet_json

get_report_pdf renders through LedgerHQ's server-side report template and returns the actual PDF bytes as base64 for agents that need to save, open, inspect, or validate a PDF. get_report_export_url returns a REST download URL plus the headers an agent must send, including the same MCP bearer token and the scoped x-organization-id value, for browser/user links.

Fixed Assets

  • list_fixed_assets
  • get_fixed_asset
  • create_fixed_asset
  • update_fixed_asset
  • delete_fixed_asset
  • depreciate_fixed_asset
  • dispose_fixed_asset
  • run_fixed_asset_depreciation

Tally

Tally MCP tools cover the same supervised AI-bookkeeper surface as the app: jobs, activity, approvals, authority, automations, evidence, firm contract, usage, standing instructions, and company month readiness.

  • start_tally_job
  • list_tally_jobs
  • get_tally_job
  • cancel_tally_job
  • get_tally_activity
  • get_tally_work_queue
  • get_tally_queue_changes
  • list_tally_approvals
  • get_tally_approval
  • decide_tally_approval
  • get_tally_authority
  • set_tally_authority
  • list_tally_automations
  • set_tally_automation
  • get_tally_automation_runs
  • get_tally_firm_contract
  • set_tally_firm_contract
  • search_tally_evidence_sources
  • get_tally_evidence_download_url
  • get_tally_usage
  • send_tally_work_report

Month-End Close

  • run_month_end_close_checks
  • list_month_end_closes
  • get_month_end_close
  • mark_month_end_close_ready
  • close_month_end
  • reopen_month_end_close

Billing, Notifications, And Utilities

The exposed MCP surface also includes Stripe integration tools, notification tools, bank rules, import/export for the supported accounting migration surface, backups, billing invoice history, tax export workpaper tools, and period close tools.

Amount Conventions

Monetary amounts in the documented LedgerHQ workflow are integer cents unless a tool description says otherwise.

Posting Transactions

Post purchases, deposits, transfers, bill payments, and journal entries through the partner API.

Direct Agent API

Give trusted staff agents direct HTTP access to the LedgerHQ admin API.

On this page

Codex: Install The LedgerHQ Plugin
Advanced Manual Setup
Plugin-Only Install
Manual Codex Plugin Setup
Claude: Connect The Remote MCP Server
Claude Code Fast Install
Claude Code Manual Install
Claude.ai, Claude Desktop, Or Cowork
How The Connection Works
Current Tool Coverage
Organization
Accounts
Journal Entries
Posting Resources
Banking Follow-Through
Statement Coverage
Reports
Fixed Assets
Tally
Month-End Close
Billing, Notifications, And Utilities
Amount Conventions