gl-importer-mcp

gl-importer（Claude Code プラグイン）

Synder Importer APIを使用して、Claude Code 内から QuickBooks Online または Xero に会計データを CSV/XLSX でインポートします。

このプラグインには、以下が含まれています。

• Synder Importer REST API（/api/v1）をラップする MCP サーバー — 読み取りと書き込みの両方に対応しています。 アカウント、会社、設定、エンティティ、フィールド、マッピング、インポート、ステータスのポーリング、結果、キャンセル、取り消しを網羅する 19 個のツールに加え、「ハッピーパス」用の複合ツールが 2 個あります。
• 2 段階のインポートフロー（ドライラン → 確認）を自然言語で案内する gl-importer エージェントスキル

要件

• Node.js 18 以降
• プラグインに対応した Claude Code（/plugin コマンドが使用可能であること）
• Synder Importer API トークン — シェル環境で IMPORTER_API_TOKEN として設定してください。 importer.synder.com → アカウント → API Keys で生成できます。

インストール

Claude Code マーケットプレイスから（推奨）

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

続いて、Claude Code を起動するシェルでトークンを設定します。

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 を、QuickBooks の会社に Bills としてインポートして。」
• 「Xero にインポートできるエンティティを教えて。」
• 「『Stripe payouts』という保存済みマッピングを表示して、Date → TxnDate にマッピングするよう更新して。」
• 「直近 10 件のインポートを一覧表示して、失敗したものを教えて。」
• 「インポート 12345 を取り消して。間違ったファイルをアップロードしてしまった。」
• 「インポート 12345 のステータスは？完了まで待って、警告の数を教えて。」

スキルは、安全な 2 段階のフローに沿って Claude Code を案内します。まず、提案されたフィールドマッピングを表示するドライランを行い、次に、インポートを実際に作成して終了するまでポーリングする確認済みの呼び出しを行います。

ツール

MCP サーバーは 19 個のツールを公開します。LLM がよく使用するツールは以下のとおりです。

ツール	用途
import_csv	簡単なフロー。 会社を自動的に特定し、ファイルをアップロードしてドライランを実行し、確認後に実行して完了まで待機します。
wait_for_import	実行中のインポートを、指数バックオフ（2s → 1.5× → 最大 30s）を使って終端状態までポーリングします。
list_companies / list_entities / get_fields	インポート先とインポート可能な項目を確認します。
list_mappings / create_mapping / update_mapping / delete_mapping	保存済みマッピングの CRUD 操作を行います。
auto_import / execute_import	低レベルの操作です。自動マッピングまたは明示的なマッピングを使ってインポートを作成します。
get_import_status / get_import_results / cancel_import / revert_import	インポートのライフサイクルを管理します。
get_settings / update_settings	会社ごとのインポート設定を管理します。
get_account	アカウント情報の確認／トークンの確認を行います。

完全なスキーマは MCP の起動時に出力されます。エージェントスキル（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

CI はプッシュと PR のたびに実行されます（.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]