Manager.io MCP

manager-mcp

セルフホスト可能な Manager.io 用 MCP サーバーです。請求書、残高、帳簿について AI に質問できます。

Manager.io とは？

Manager.io は、Windows、macOS、Linux 向けの無料のセルフホスト可能な会計ソフトウェアです（Cloud Edition も利用できます）。売上、仕入、銀行取引、給与計算、総勘定元帳全体を扱い、自動化向けの HTTP API（/api2）を備えています。

このプロジェクトは、その API を Model Context Protocol に接続し、Cursor、Claude、VS Code Copilot、その他の MCP ホストから、自然言語でリアルタイムの帳簿を照会できるようにします。

Manager.io の便利なリンク：

• ダウンロード
• ガイド
• フォーラム
• リリース

このサーバーでできること

デフォルトは読み取り専用です。次の機能を利用できます。

• 読み取りツール 10 個 - 検出、検索可能な 6 つのコレクション、7 つのレポートショートカット
• タスクツール（オプトイン） - record_customer_payment、issue_sales_invoice、record_customer_deposit など、意図に応じた書き込み機能（一致する書き込みスコープが設定されている場合に登録）
• 非推奨の CRUD ツール - リソースごとの create_* / update_* / delete_* は、0.3.0 まではスコープに応じて引き続き登録されます。タスクツールを優先してください
• raw エスケープハッチ - 高度な用途向けに、CRUD ツール一式をすべて有効にします
• 厳格な拒否リスト - アクセストークン、勘定科目表フォーム、税／通貨、メールテンプレートなど、リスクの高いパスは書き込みが有効でも引き続きブロックされます

トランスポートは stdio です。HTTP サーバーはありません。uv / uvx を使えば、グローバルインストールは不要です。

ブランディング／アイコン

• stdio ホスト（Cursor、mcp.json 経由の Claude Desktop）： サーバーは MCP の serverInfo.icons で Manager のブランディングを通知します（埋め込み PNG データ URI と、GitHub の raw HTTPS フォールバック）。
• Cursor プラグイン： .cursor-plugin/plugin.json は docs/manager-icon.svg を使用します。
• Claude Desktop Extension： mcpb/ をパッケージ化します（icon.png を含む）。「インストール」→「Claude Desktop」を参照してください。
• Claude.ai リモートコネクター： Claude.ai は serverInfo.icons を無視し、コネクター URL のルートドメインのファビコンを使用します。後でリモート MCP をホストする場合は、登録可能ドメインのルートで docs/favicon.ico を配信してください（例：https://mcp.acme.com/... の場合は https://acme.com/favicon.ico）。

要件

• Python ≥ 3.10（uvx により自動的にインストールされます）
• uv（uvx を提供）
• 接続可能な Manager.io API：MANAGER_API_URL + MANAGER_API_KEY

アクセストークン

1. Manager で 設定 → アクセストークン を開きます。
2. トークンを作成し、その値を MANAGER_API_KEY にコピーします。
3. MANAGER_API_URL に API のベース URL を設定します（デスクトップ版では通常 http://127.0.0.1:55667/api2）。

manager-mcp はトークンを X-API-KEY ヘッダーとして送信します。手順の詳細は、アクセストークンを参照してください。

クイックスタート

uvx を使って、PyPI パッケージを実行します。

uvx manager-mcp

以下にクライアント設定を貼り付け、MANAGER_API_URL / MANAGER_API_KEY を設定してホストを再起動し、「未回収のお金はいくらありますか？」や「銀行残高を表示して」と尋ねます。

Git クローンから実行する場合（開発用）：uvx --from git+https://github.com/flumpiey/manager-mcp manager-mcp または uv run --directory /path/to/manager-mcp manager-mcp。

インストール

以下の設定では、PyPI から manager-mcp を取得します。読み取り専用にする場合は、書き込みスコープの環境変数を設定しないでください。

{
  "mcpServers": {
    "manager": {
      "type": "stdio",
      "command": "uvx",
      "args": ["manager-mcp"],
      "env": {
        "MANAGER_API_URL": "http://127.0.0.1:55667/api2",
        "MANAGER_API_KEY": "your-token"
      }
    }
  }
}

{
  "mcpServers": {
    "manager": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/manager-mcp", "manager-mcp"],
      "env": {
        "MANAGER_API_URL": "http://127.0.0.1:55667/api2",
        "MANAGER_API_KEY": "your-token"
      }
    }
  }
}

"MANAGER_MCP_WRITE_SCOPES": "quotes",
"MANAGER_MCP_DELETE_SCOPES": "quotes"

npx @anthropic-ai/mcpb pack mcpb

{
  "mcpServers": {
    "manager": {
      "command": "uvx",
      "args": ["manager-mcp"],
      "env": {
        "MANAGER_API_URL": "http://127.0.0.1:55667/api2",
        "MANAGER_API_KEY": "your-token"
      }
    }
  }
}

{
  "mcpServers": {
    "manager": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/manager-mcp", "manager-mcp"],
      "env": {
        "MANAGER_API_URL": "http://127.0.0.1:55667/api2",
        "MANAGER_API_KEY": "your-token"
      }
    }
  }
}

claude mcp add manager --env MANAGER_API_URL=http://127.0.0.1:55667/api2 --env MANAGER_API_KEY=your-token -- uvx manager-mcp

{
  "mcpServers": {
    "manager": {
      "command": "uvx",
      "args": ["manager-mcp"],
      "env": {
        "MANAGER_API_URL": "http://127.0.0.1:55667/api2",
        "MANAGER_API_KEY": "your-token"
      }
    }
  }
}

{
  "servers": {
    "manager": {
      "type": "stdio",
      "command": "uvx",
      "args": ["manager-mcp"],
      "env": {
        "MANAGER_API_URL": "http://127.0.0.1:55667/api2",
        "MANAGER_API_KEY": "your-token"
      }
    }
  }
}

{
  "servers": {
    "manager": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/manager-mcp", "manager-mcp"],
      "env": {
        "MANAGER_API_URL": "http://127.0.0.1:55667/api2",
        "MANAGER_API_KEY": "your-token"
      }
    }
  }
}

{
  "mcpServers": {
    "manager": {
      "command": "uvx",
      "args": ["manager-mcp"],
      "env": {
        "MANAGER_API_URL": "http://127.0.0.1:55667/api2",
        "MANAGER_API_KEY": "your-token"
      }
    }
  }
}

{
  "context_servers": {
    "manager": {
      "command": "uvx",
      "args": ["manager-mcp"],
      "env": {
        "MANAGER_API_URL": "http://127.0.0.1:55667/api2",
        "MANAGER_API_KEY": "your-token"
      }
    }
  }
}

{
  "mcpServers": {
    "manager": {
      "command": "uvx",
      "args": ["manager-mcp"],
      "env": {
        "MANAGER_API_URL": "http://127.0.0.1:55667/api2",
        "MANAGER_API_KEY": "your-token"
      }
    }
  }
}

mcpServers:
  - name: manager
    command: uvx
    args:
      - manager-mcp
    env:
      MANAGER_API_URL: http://127.0.0.1:55667/api2
      MANAGER_API_KEY: your-token

uvx manager-mcp

有効なスコープ：quotes、orders、parties、items、sales、purchases、banking、payroll、ledger、raw。ワイルドカード（*、all）は使用できません。

推奨（82 個のツールを使わずに、ほとんどの簿記作業に対応します）：

"MANAGER_MCP_WRITE_SCOPES": "banking,sales,parties",
"MANAGER_MCP_DELETE_SCOPES": "sales,banking"

スコープを指定しない場合のデフォルトは 10 個のツールです。9 つすべてのドメインスコープとすべての CRUD 操作を有効にすると、最大 82 個のツールになります。CRUD の完全な例外機能が必要な場合のみ、raw を使用してください。

レガシー変数 MANAGER_MCP_ALLOW_WRITES／ALLOW_WRITES／MANAGER_MCP_WRITES が設定されている場合、処理は失敗します。代わりにスコープ指定の変数を使用してください。

.env.example を参照してください。本番環境の設定では、API キーにシークレットマネージャーを使用することを推奨します。

書き込みスコープとタスクツール

MANAGER_MCP_WRITE_SCOPES にスコープを指定すると、サーバーはそのドメインのタスクツールと、非推奨の CRUD ツールを登録します。MANAGER_MCP_DELETE_SCOPES を指定すると、ドメインごとに void_document と delete_* が有効になります。

タスクツール（推奨）

複合ツールの本文では、記載がある場合、Manager ネイティブの JSON を使用します。get_record のテンプレートを複製し、フィールド名を独自に作成しないでください。

非推奨の CRUD（0.2.0、0.3.0 で削除）

ドメインスコープが有効な場合、リソースごとの create_*／update_*／delete_* も引き続き登録されます。create_customer／create_supplier を除き、説明の先頭には [DEPRECATED in 0.2.0; use task tools] が付加されます。MANAGER_MCP_WRITE_SCOPES に raw を設定すると、非推奨のプレフィックスなしで CRUD が登録されます。

推奨スコープのみを使用する例：

"MANAGER_MCP_WRITE_SCOPES": "banking,sales,parties",
"MANAGER_MCP_DELETE_SCOPES": "sales"

拒否リスト（常にブロック）： アクセストークン関連の形式、勘定科目表／*-account-form（bank-or-cash を除く）、銀行照合、顧客ポータル、開始残高、税コード、為替レート、通貨、カスタムフィールド／ボタン、テーマ、メールテンプレート／設定。

顧客からの前受金ワークフロー

前受金は収益ではありません。納品前に受け取った金額を収益勘定に計上してはいけません。税金／VAT の扱いについては、会計士に確認してください。

1. Manager に Customer deposits 銀行／現金勘定があることを確認します（Settings → Bank and Cash Accounts）。
2. record_customer_deposit - 現金をその勘定に計上します。勘定がない場合、このツールは正確な設定手順を含む precondition_failed を返します（オプション A：ガイドのみ、自動作成なし）。
3. issue_deposit_invoice（任意） - 顧客向けに、前受金書類の形式で見積書を作成します。
4. 実際の請求書を発行する際に issue_sales_invoice を実行します。
5. apply_deposit_to_invoice - 前受金残高を請求書に移す仕訳です（get_record で既存の仕訳を複製します）。

必要なスコープ：banking、quotes（前受金書類）、ledger（適用）、sales（MCP 経由での最終請求書）。

0.1.x からの移行

• 0.2.0：タスクツールが追加されました。CRUD ツールは非推奨になりましたが、スコープ内には引き続き存在します。
• 0.3.0：CRUD ツールが削除されました（create_customer / create_supplier を除く）。タスクツールまたは raw スコープを使用してください。
• すべてのドメインを有効にするのではなく、MANAGER_MCP_WRITE_SCOPES を上記の推奨される限定的な設定に更新してください。

ツール

読み取りツール

list_records / get_record のコレクション：customers、suppliers、sales_invoices、purchase_invoices、chart_of_accounts、bank_accounts。

chart_of_accounts は一覧／検索のみです（単一フォームへの GET はありません）。

銀行のデュアルパス（意図的な設計）： bank_balances は「残高はいくらか？」に答え、bank_accounts に対する list_records / get_record は「口座 X を検索して詳細を表示」に答えます。

書き込みツール（非推奨）

有効なスコープ内のリソースに対してのみ登録されます。上記のタスクツールを優先してください。

エージェントスキル

関連スキル：skills/manager-accounting/SKILL.md。

Cursor プラグインは skills/ からこのスキルを検出します。プラグインを使用しない場合は、そのフォルダーをエージェントのスキルパスにコピーするか、シンボリックリンクを作成してください。このスキルでは、モデルに最初に list_resources を呼び出すこと、書き込み後に検証すること、優先するレポートツールを指示します。

開発

uv sync --extra dev
uv run manager-mcp

オフラインテストのみ（respx）。Manager の実環境は不要です：

uv run ruff check src tests
uv run pytest

GitHub Actions のマトリックス：Python 3.10 および 3.12。

注意事項

• 1 プロセス ↔ 1 つの MANAGER_API_URL。複数インスタンスへのルーティングは対象外です。
• 共有ホストでの複数事業の識別は未検証です。複数事業のサポートを主張する前に、複数事業の実環境で検証してください。
• ベンダー提供の src/manager_mcp/spec/api2.json は出所の記録用のみです。実行時には常にライブ URL にアクセスします。
• ChatGPT Apps にはホスト型の HTTP MCP エンドポイントが必要です。このパッケージは stdio 専用です。

ライセンス

MIT。LICENSE を参照してください。