# `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:

```bash
nvm use 18.16.1
pnpm install
pnpm typecheck
pnpm build
```

Run locally:

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

## Install From npm

```bash
npm install -g @reomar/mcp-bigcapital
```

## AI Agent Installation Prompt

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

```text
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](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:

```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:

```json
{
  "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.