The gl-importer server lets you import CSV/XLSX accounting data into QuickBooks Online or Xero via the Synder Importer API, with full lifecycle management of imports and mappings.
Account & Companies
Verify your API token and view account details (email, status, subscription) with get_account
List connected accounting companies (QuickBooks Online / Xero) with list_companies
Discovery
List importable entity types for a company (Invoice, Bill, JournalEntry, Customer, Vendor, etc.) with list_entities
Inspect field schemas (types, required flags, allowed values, column aliases) with get_fields
Settings
Read per-company import settings (date format, duplicate handling, auto-creation rules) with get_settings
Selectively update per-company import settings with update_settings
Field Mapping CRUD
List, create, update, and delete saved field mappings (list_mappings, create_mapping, update_mapping, delete_mapping)
Running Imports
Happy-path two-step flow: dry-run to preview auto-proposed mapping, then confirm to execute with import_csv
Auto-map and import a file in one call (or dry-run only) with auto_import
Execute an import using an existing saved mapping with execute_import
Supports .csv, .xlsx, .xls files up to 50MB
Import Lifecycle & Monitoring
List recent imports with list_imports
Check import status (SCHEDULED → IN_PROGRESS → FINISHED / FAILED / CANCELED) with get_import_status
Poll an import to completion with exponential backoff with wait_for_import
Retrieve per-row results (INFO / WARNING / ERROR), paginated and filterable, with get_import_results
Cancel a running import with cancel_import
Revert a finished import (deletes the created QBO/Xero entries) with revert_import
Provides tools for importing CSV/XLSX accounting data into QuickBooks Online, including dry-run import, mapping management, and lifecycle operations.
Provides tools for importing CSV/XLSX accounting data into Xero, including dry-run import, mapping management, and lifecycle operations.
Import CSV/XLSX accounting data into QuickBooks Online or Xero from inside Claude Code, using the Synder Importer API.
This plugin bundles:
An MCP server wrapping the Synder Importer REST API (/api/v1) — full read + write,
19 tools covering account, companies, settings, entities, fields, mappings, imports,
status polling, results, cancel, revert, plus two composite "happy path" tools.
The gl-importer agent skill with natural-language guidance for the two-step
import flow (dry-run → confirm).
Node.js 18 or newer
Claude Code with plugin support (/plugin command available)
A Synder Importer API token — set as IMPORTER_API_TOKEN in your shell env.
Generate at importer.synder.com → Account → API Keys.
Related MCP server: qb-mcp
/plugin marketplace add SynderAccounting/gl-importer-plugin
/plugin install gl-importerThen set your token in the shell that launches Claude Code:
export IMPORTER_API_TOKEN="your_token_here"Download the latest .mcpb bundle from Releases and double-click it. Claude Desktop will prompt you for the API token.
git clone https://github.com/SynderAccounting/gl-importer-plugin
cd gl-importer-plugin
npm install
npm run build
# Point Claude Code at this directory:
claude --plugin-dir .Env var | Required | Default | Purpose |
| yes | — | Bearer token for the Synder Importer API |
| no |
| Override for staging/test |
Once installed, talk to Claude Code naturally:
"Import ~/Downloads/march-bills.csv as Bills into my QuickBooks company."
"What entities can I import into Xero?"
"Show me the saved mapping called 'Stripe payouts' and update it to map Date → TxnDate."
"List my last 10 imports and tell me which ones failed."
"Revert import 12345 — I uploaded the wrong file."
"What's the status of import 12345? Wait for it to finish and tell me how many warnings."
The skill will walk Claude Code through a safe two-step flow: a dry-run that shows the proposed field mapping, then a confirmed call that actually creates the import and polls until it terminates.
The MCP server exposes 19 tools. The ones an LLM will hit most often:
Tool | Purpose |
| Happy path. Auto-resolves company, uploads file, runs dry-run, then (on confirm) executes + waits. |
| Polls a running import to a terminal state with exponential backoff (2s → 1.5× → 30s cap). |
| Discover what you can import where. |
| Saved-mapping CRUD. |
| Lower-level: create an import with auto-mapping or an explicit mapping. |
| Lifecycle. |
| Per-company import settings. |
| Whoami / token check. |
Full schemas are emitted at MCP startup — the agent skill (skills/gl-importer/SKILL.md)
also documents the conventions.
npm install
npm run build # tsc → dist/
npm test # vitest, 60+ unit tests, virtual-clock polling tests
npm run watch # tsc --watch for iterative devCI runs on every push and PR (.github/workflows/ci.yml).
Bump version in package.json and .claude-plugin/plugin.json (keep them in sync).
Commit and tag: git tag v0.x.y && git push --tags.
The publish.yml workflow publishes to npm on the tag push (uses NPM_TOKEN secret).
The marketplace install path resolves through this GitHub repo, so the tag is the release.
MIT — see LICENSE.
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.
Inputs: companyId (required), filePath (required), entityName (required), dryRun. Returns: Either an import object (dryRun=false) or a proposed mapping with detected colu…
Cancels a SCHEDULED or IN_PROGRESS import. Already-imported rows are NOT rolled back — use revert_import for that. Returns the updated import status.
Inputs: companyId (required), importId (required). Returns: id, status, entityName, fileName, +3 more
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.
Inputs: companyId (required), title (required), entityName (required), fields (required). Returns: id, title, entityName, fields, +2 more
Deletes a saved mapping. Irreversible. Imports that referenced this mapping keep their historical record but new imports can no longer pick it.
Inputs: companyId (required), mappingId (required). Returns: deleted, mappingId
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.
Inputs: companyId (required), filePath (required), entityName (required), mappingId (required). Returns: id, status, entityName, fileName, +3 more
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.
Inputs: no named parameters. Returns: id, email, name, status, +2 more
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.
Inputs: companyId (required), entityName (required). Returns: fields
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.
Inputs: companyId (required), importId (required), type, page, +1 more. Returns: rows, page, perPage, total, +1 more
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.
Inputs: companyId (required), importId (required). Returns: id, status, entityName, fileName, +3 more
Returns per-company import settings (dateFormat, document-number behavior, product/account auto-creation, duplicate-skip). Check dateFormat before importing — CSV date columns must match.
Inputs: companyId (required). Returns: dateFormat, incrementDocNumber, createMissingProducts, createMissingAccounts, +…
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? }.
Inputs: filePath (required), entityName (required), companyId, confirmed, +1 more. Returns: stage, companyId, entityName, importId, +5 more
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.
Inputs: no named parameters. Returns: companies
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.
Inputs: companyId (required). Returns: entities
Lists recent imports for a company with status and timestamps. Use to find an importId for status / results / revert / cancel.
Inputs: companyId (required). Returns: imports
Lists field mappings saved for a company. Each mapping is reusable across imports of the same entity type.
Inputs: companyId (required). Returns: mappings
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.
Inputs: companyId (required), importId (required). Returns: id, status, entityName, fileName, +3 more
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.
Inputs: companyId (required), mappingId (required), title (required), entityName (required), +1 more. Returns: id, title, entityName, fields, +2 more
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.
Inputs: companyId (required), settings (required). Returns: dateFormat, incrementDocNumber, createMissingProducts, createMissingAccounts, +…
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).
Inputs: companyId (required), importId (required), timeoutSeconds. Returns: id, status, importId, summary, +1 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 19 tools
Most tools have distinct purposes, but there is some overlap between auto_import, import_csv, and execute_import. Detailed descriptions help differentiate them, though an agent might still need to read carefully.
All tool names follow a consistent verb_noun pattern with underscores, e.g., create_mapping, list_companies. Very predictable and easy to understand.
19 tools is appropriate for an import server covering account info, companies, entities, mappings, multiple import workflows, settings, and results. Each tool earns its place.
The tool set covers the full import lifecycle: mapping CRUD, multiple import methods, status polling, results, cancellation, reversion, and settings management. No obvious gaps.
Apideck Unified API MCP — 330 tools across 200+ SaaS connectors (accounting, CRM, HRIS, ATS).
Make a Stripe monthly report, turn your PayPal transaction history into Excel.
Connect any two APIs and keep them in sync — 50 MCP tools with shadow previews and diagnostics.
Convert journals between A3, ContaPlus/Sage 50, QuickBooks, Xero and CSV; bank files to entries.
