mcp-bigcapital

Unofficial API wrapper. This is an independent MCP integration and is not affiliated with, endorsed by, or supported by Bigcapital.

Testing disclaimer. This package needs broader testing before it should be relied on for production accounting workflows. It was developed and tested against Bigcapital v0.25.20.

Standalone stdio MCP server for Bigcapital. Its internal SDK and official OpenAPI spec are included under packages/sdk-ts so a fresh clone can install and build without the Bigcapital monorepo.

Environment

Required:

• BIGCAPITAL_BASE_URL
• BIGCAPITAL_API_KEY

Optional:

• BIGCAPITAL_ORGANIZATION_ID
• BIGCAPITAL_TOOL_PROFILE (agency by default, or full)

BIGCAPITAL_BASE_URL should be the Bigcapital app origin, for example http://localhost:3000. Do not append /api.

The server sends:

• Authorization: Bearer <BIGCAPITAL_API_KEY>
• organization-id: <BIGCAPITAL_ORGANIZATION_ID> when configured

Tool Profiles

The default agency profile exposes a focused set of day-to-day tools for customers, vendors, service items, invoices, payments, sale receipts, bills, expenses, manual journals, core financial reports, and attachments. This keeps the MCP tool catalog smaller for AI clients.

Set BIGCAPITAL_TOOL_PROFILE=full to expose every implemented tool, including administration, inventory, banking, configuration, destructive actions, and specialized workflows.

Build And Run

From the repository root:

nvm use 18.16.1
pnpm install
pnpm typecheck
pnpm build

Run locally:

BIGCAPITAL_BASE_URL=http://localhost:3000 \
BIGCAPITAL_API_KEY=bc_your_api_key_here \
node dist/index.js

Install From npm

npm install -g @reomar/mcp-bigcapital

AI Agent Installation Prompt

Copy this prompt into an AI coding agent that can manage MCP servers:

Install and configure the Bigcapital MCP server from npm for this workspace.

1. Install the package globally: npm install -g @reomar/mcp-bigcapital
2. Add an MCP server named "bigcapital" that runs the command: mcp-bigcapital
3. Configure these environment variables without printing their values:
   - BIGCAPITAL_BASE_URL: the Bigcapital application origin, without /api
   - BIGCAPITAL_API_KEY: my Bigcapital API key
   - BIGCAPITAL_ORGANIZATION_ID: my organization ID, if required
   - BIGCAPITAL_TOOL_PROFILE: agency
4. Verify that the server starts and can list its tools.
5. Do not expose, commit, or log API keys.

Use the agency profile unless I explicitly ask for the full Bigcapital API toolset.

Tool Coverage

Current tool categories:

• Organization and configuration: organization, branches, currencies, tax rates, PDF templates, payment services, settings, views, date formats, dashboard boot metadata
• Core records: customers, vendors, items, accounts, invoices, bills, expenses
• Accounting workflows: sale estimates, sale receipts, payments received, bill payments, credit notes, vendor credits, manual journals
• Inventory: warehouses, warehouse transfers, inventory adjustments, inventory cost, item categories
• Reports: profit/loss, balance sheet, trial balance, cashflow, general ledger, journal, item sales/purchases, customer/vendor balance summaries, aging, inventory, sales tax, transaction reports
• Banking and attachments: banking read/categorization tools, attachment upload/delete/presigned URL
• Admin reads: users, roles, API keys, subscriptions, exchange rates

Detailed coverage inventory is generated in docs/api-coverage.md.

Safety

Destructive tools require confirm: true. This includes delete and bulk-delete operations, plus other irreversible mutations such as deleting attachments or payment methods.

MCP Configuration

Hermes/Codex-style YAML:

mcp_servers:
  bigcapital:
    command: "node"
    args: ["/absolute/path/to/mcp-bigcapital/dist/index.js"]
    env:
      BIGCAPITAL_BASE_URL: "https://your-bigcapital.example.com"
      BIGCAPITAL_API_KEY: "bc_..."
      BIGCAPITAL_ORGANIZATION_ID: "..."

JSON-style config:

{
  "mcpServers": {
    "bigcapital": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-bigcapital/dist/index.js"],
      "env": {
        "BIGCAPITAL_BASE_URL": "https://your-bigcapital.example.com",
        "BIGCAPITAL_API_KEY": "bc_...",
        "BIGCAPITAL_ORGANIZATION_ID": "..."
      }
    }
  }
}

Notes

• The MCP package prefers existing helpers from @bigcapital/sdk-ts; raw HTTP is only used for a few gaps where the OpenAPI path exists but the SDK helper was not yet present.
• Create/update bodies are intentionally permissive on many tools and pass through to the SDK to stay aligned with the evolving OpenAPI schema.
• The server exits early with a clear configuration error when required env vars are missing. That no-env failure mode is intentional for smoke testing.