gl-importer-mcp

gl-importer（Claude Code 插件）

在 Claude Code 中使用 Synder Importer API，将 CSV/XLSX 会计数据导入 QuickBooks Online 或 Xero。

此插件包含：

• 一个封装 Synder Importer REST API（/api/v1）的 MCP 服务——支持完整的读写操作，包含 19 个工具，涵盖账户、公司、设置、实体、字段、映射、导入、状态轮询、结果、取消、撤销，以及两个复合式「顺利流程」工具。
• gl-importer Agent 技能，提供自然语言指引，帮助完成两步导入流程（试运行 → 确认）。

要求

• Node.js 18 或更高版本
• 支持插件的 Claude Code（可使用 /plugin 命令）
• Synder Importer API 令牌——在 shell 环境中设置为 IMPORTER_API_TOKEN。 前往 importer.synder.com → Account → API Keys 生成。

安装

从 Claude Code 插件市场安装（推荐）

/plugin marketplace add SynderAccounting/gl-importer-plugin
/plugin install gl-importer

然后在启动 Claude Code 的 shell 中设置令牌：

export IMPORTER_API_TOKEN="your_token_here"

Claude Desktop（一键安装 MCP）

从 Releases 下载最新的 .mcpb 软件包，然后双击。Claude Desktop 会提示你输入 API 令牌。

从源代码安装（开发）

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 .

配置

环境变量	必需	默认值	用途
IMPORTER_API_TOKEN	是	—	Synder Importer API 的 Bearer 令牌
IMPORTER_BASE_URL	否	https://importer.synder.com/api/v1	用于暂存/测试环境的覆盖项

示例提示词

安装后，可以用自然语言与 Claude Code 对话：

• 「将 ~/Downloads/march-bills.csv 作为 Bills 导入我的 QuickBooks 公司。」
• 「我可以向 Xero 导入哪些实体？」
• 「显示名为 'Stripe payouts' 的已保存映射，并将其更新为 Date → TxnDate。」
• 「列出我最近 10 次导入，并告诉我哪些失败了。」
• 「撤销导入 12345——我上传了错误的文件。」
• 「导入 12345 的状态是什么？等它完成后，告诉我有多少条警告。」

该技能会引导 Claude Code 安全地完成两步流程：先进行试运行，显示建议的字段映射；然后执行确认调用，实际创建导入并持续轮询，直到导入结束。

工具

MCP 服务提供 19 个工具。LLM 最常用的工具如下：

工具	用途
import_csv	顺利流程。 自动解析公司、上传文件、运行试运行，然后（确认后）执行并等待。
wait_for_import	以指数退避方式轮询正在运行的导入，直到到达终态（2 秒 → 1.5× → 上限 30 秒）。
list_companies / list_entities / get_fields	查找可向哪些公司导入哪些内容。
list_mappings / create_mapping / update_mapping / delete_mapping	已保存映射的增删改查。
auto_import / execute_import	较底层的工具：使用自动映射或显式映射创建导入。
get_import_status / get_import_results / cancel_import / revert_import	管理导入生命周期。
get_settings / update_settings	按公司设置导入选项。
get_account	查看当前身份 / 检查令牌。

完整 schema 会在 MCP 启动时输出——Agent 技能（skills/gl-importer/SKILL.md）也记录了相关约定。

开发

npm install
npm run build       # tsc → dist/
npm test            # vitest, 60+ unit tests, virtual-clock polling tests
npm run watch       # tsc --watch for iterative dev

每次推送和 PR 都会运行 CI（.github/workflows/ci.yml）。

发布流程

1. 更新 package.json 和 .claude-plugin/plugin.json 中的 version（确保两者保持一致）。
2. 提交并创建标签：git tag v0.x.y && git push --tags。
3. publish.yml 工作流会在推送标签时发布到 npm（使用 NPM_TOKEN 密钥）。
4. 插件市场的安装路径会通过此 GitHub 仓库解析，因此标签即为版本发布。

许可证

MIT——参见 LICENSE。

支持

• 问题反馈：https://github.com/SynderAccounting/gl-importer-plugin/issues
• 电子邮件：[email protected]