# SynderAccounting/gl-importer-plugin [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/SynderAccounting/gl-importer-plugin  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1086  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/synderaccounting-gl-importer-plugin

## Description
Import CSV/XLSX accounting data into QuickBooks Online or Xero via the Synder Importer API. 19 tools covering imports, field mapping rules, post-import rules, and entity discovery. Install with npx -y @cloudbusiness/gl-importer-mcp.

## Tools
Capabilities this server exposes over MCP:

- **get_account** — Returns the current Synder Importer account: email, name, status, subscription, and connected-company count. Call this first to verify the IMPORTER_API_TOKEN is valid.
- **list_companies** — Lists all accounting companies connected to the Importer account (QuickBooks Online via 'intuit', Xero via 'xero'). Use the returned 'id' as companyId for downstream tools.
- **get_settings** — Returns per-company import settings (dateFormat, document-number behavior, product/account auto-creation, duplicate-skip). Check dateFormat before importing — CSV date columns must match.
- **update_settings** — Updates per-company import settings. Pass only the fields you want to change inside 'settings' (e.g. { dateFormat: 'dd/MM/yyyy' }). Fetch current values with get_settings first so you don't clobber unrelated fields. Returns the updated settings.
- **list_entities** — Lists importable entity types for a company (Invoice, Bill, JournalEntry, Customer, Vendor, etc.). Use the returned 'name' as entityName for get_fields and import tools.
- **get_fields** — Returns the field schema for an entity in a company: every field with its type, required flag, alternativeTitles, and predefinedValues. Use to build or verify a mapping before running an import.
- **list_mappings** — Lists field mappings saved for a company. Each mapping is reusable across imports of the same entity type.
- **create_mapping** — Creates a new field mapping for an entity (e.g. 'Journal Entry', 'Bill', 'Invoice'). Look up valid target fields with get_fields first. Returns the created mapping including its id.
- **update_mapping** — Replaces an existing mapping in full. Fetch the current mapping with list_mappings first and send the whole desired shape — this is a PUT, not a patch. Returns the updated mapping.
- **delete_mapping** — Deletes a saved mapping. Irreversible. Imports that referenced this mapping keep their historical record but new imports can no longer pick it.
- **list_imports** — Lists recent imports for a company with status and timestamps. Use to find an importId for status / results / revert / cancel.
- **get_import_status** — Returns a single import's current status and summary (total / succeeded / failed / warnings). Status lifecycle: SCHEDULED → IN_PROGRESS → FINISHED | FINISHED_WITH_WARNINGS | FAILED | CANCELED. FINISHED can transition to REVERTING → REVERTED.
- **get_import_results** — Returns per-row results for a finished import. Filter by 'type' (INFO / WARNING / ERROR) to surface only failures. Paginated — defaults to 20 rows per page, max 100.
- **execute_import** — Uploads a CSV/XLSX file and starts an import using an existing mapping. The MCP server reads the file from disk — pass an absolute path. Returns the created import object including importId. Status starts as SCHEDULED — poll get_import_status or use wait_for_import. Limits: .csv/.xlsx/.xls only, 50MB max.
- **auto_import** — Uploads a file and asks the server to auto-map columns to the target entity. Set dryRun=true to get the proposed mapping back without creating an import — useful for showing the user what will happen and asking 'does this look right?' before committing. Set dryRun=false (default) to auto-map and import in one call.
- **cancel_import** — Cancels a SCHEDULED or IN_PROGRESS import. Already-imported rows are NOT rolled back — use revert_import for that. Returns the updated import status.
- **revert_import** — Reverts a FINISHED or FINISHED_WITH_WARNINGS import — deletes the QuickBooks/Xero entries the import created, using their live SyncTokens. Status transitions FINISHED → REVERTING → REVERTED. Confirm with the user before calling — irreversible from their perspective.
- **wait_for_import** — Polls get_import_status until the import reaches a terminal state (FINISHED, FINISHED_WITH_WARNINGS, FAILED, CANCELED, REVERTED). Exponential backoff (2s → 1.5× → cap 30s). Default timeout 600s — if exceeded, returns { status: 'POLLING', importId, lastSeen } so the LLM can re-call. Includes a per-type result count summary on terminal states (INFO / WARNING / ERROR; null if the server didn't return totals).
- **import_csv** — Happy-path CSV/XLSX importer. Two-step: first call (without confirmed) auto-resolves the company, uploads the file, and returns the server's proposed mapping plus any missingRequired fields — show this to the user. Re-call with confirmed=true (and the same filePath) to run the real import and poll until it terminates. Returns { stage: 'DRY_RUN' | 'DONE', importId?, status, summary?, proposedMapping?, missingRequired? }.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "gl-importer-plugin": {
    "command": "npx",
    "args": ["-y","@cloudbusiness/gl-importer-mcp"],
    "env": {
      "IMPORTER_API_TOKEN": "",
      "IMPORTER_BASE_URL": ""
    }
  }
}
```

**Requires environment variables:** `IMPORTER_API_TOKEN`, `IMPORTER_BASE_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What SynderAccounting/gl-importer-plugin does

SynderAccounting/gl-importer-plugin exposes the Synder Importer REST API as MCP tools for importing accounting data from CSV and XLSX files. It supports QuickBooks Online and Xero targets, with tools for discovering available companies, entities, and fields before an import is created.

The package is intended for workflows where an agent needs to inspect or transform an import configuration rather than merely upload a file. It can create and manage saved field mappings, read company-specific settings, check the authenticated account, and inspect import results. Lifecycle operations include checking status, waiting for completion, cancelling an active import, and reverting an import.

This belongs in the Finance & Fintech category and is most relevant when accounting data starts in spreadsheets or exported files and must be sent to a supported accounting company through Synder.

## How it works

The primary `import_csv` tool provides a guided path. It resolves the target company, uploads the file, and performs a dry run. The dry run exposes the proposed mapping for review; execution happens only after confirmation. Once execution begins, the workflow can poll until the import reaches a terminal state.

For more control, `auto_import` creates an import using automatic mapping or an explicitly supplied mapping. Separate tools support direct execution and lifecycle management. `wait_for_import` uses exponential backoff, starting at two seconds, multiplying by 1.5, and capping the interval at 30 seconds.

The server communicates with the Synder Importer API at `/api/v1`. MCP schemas are emitted when the server starts, allowing clients to discover the available tool inputs and outputs.

## Setup and configuration

SynderAccounting/gl-importer-plugin requires Node.js 18 or newer and a Synder Importer API token. Create the token in Synder under Account → API Keys, then provide it in the shell or client configuration as `IMPORTER_API_TOKEN`.

The default API endpoint is `https://importer.synder.com/api/v1`. Set `IMPORTER_BASE_URL` to use another endpoint, such as a staging or test service. The repository documents installation through the Claude Code marketplace, from source, or with the published MCP package. Source installation uses `npm install` followed by `npm run build`.

Claude Desktop users can install the latest `.mcpb` bundle from the repository releases and enter the API token when prompted. Claude Code users can install the marketplace plugin or point Claude Code at a local checkout.

## Tools and capabilities

The 19 tools cover these areas:

- Discover accounts, companies, entities, and importable fields.
- Create, list, update, and delete saved mappings.
- Run automatic or explicit mappings for imports.
- Perform the dry-run, confirmation, and wait workflow.
- Read import status and results.
- Cancel or revert imports.
- Read and update per-company import settings.
- Verify the current API account and token.

The SynderAccounting/gl-importer-plugin agent skill adds natural-language guidance for the two-step dry-run and confirmation process. This helps keep file imports separate from the final execution decision, but the target company, file, entity, and mapping still need to be appropriate for the accounting data.

## Limitations and notes

The material documents QuickBooks Online and Xero as supported destinations; it does not identify other accounting platforms. An API token is required, and the server depends on access to the Synder Importer API. Claude Code plugin support is required for the marketplace installation path. The documentation does not state that Cursor, Windsurf, or Cline are supported clients.

SynderAccounting/gl-importer-plugin is licensed under MIT. Issues are handled in the GitHub repository, and the documented support email is help@synder.com.

_Full upstream README: https://allmcps.com/mcp/synderaccounting-gl-importer-plugin/readme_