BagOS

🚀 インストール

npx bagos-mcp-server

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "bagos": {
      "command": "npx",
      "args": ["-y", "bagos-mcp-server"],
      "env": {
        "BAGS_API_KEY": "your-key-here"
      }
    }
  }
}

Claude Code：

claude mcp add bagos --env BAGS_API_KEY=your-key-here -- npx -y bagos-mcp-server

クライアントを再起動して、「Bags のトップクリエイターを表示して」と尋ねてください。サーバーは起動時に stderr へ設定レポートを出力します。不足している設定があれば、該当する変数とその理由が示されます。

API キーだけで、11 個ある読み取りツールのうち 8 個を利用できます。bags_heartbeat、bags_get_claimable_fees、bags_authenticate の 3 つはあなたのウォレットについて報告するため、BAGS_KEYPAIR_PATH も必要です。設定されていない場合はエラーになります。書き込みは、設定するまで無効です（はじめに）。

🔒 アシスタントに安心して任せられる理由

• 最初の呼び出しでは署名されません。 書き込みツールはプレビューと、その引数に厳密にひも付けられた使い捨てトークンのフィンガープリントを返します。トークンを指定して再度呼び出すまで、チェーンへの送信は行われません。
• SOL の上限が厳格に設定されています。 取引ごとに 0.1、セッションごとに 1 がデフォルトの上限で、Bags SDK が呼び出される前に拒否されます。
• デフォルトでは Devnet です。 書き込みは Mainnet でのみ可能なため、設定されていないインストール環境で実際の資金が使われることはありません。

脅威モデル、開示ポリシー、各制御の制限については、.github/SECURITY.md をご覧ください。

⚠️ 1.x をお使いの場合 — v2.0.0 で重大な不具合が修正されました

v2.0.0 で重大な不具合が修正されました。 1.x では書き込みツールがトランザクションを構築した後に破棄し、成功したと報告していました。署名も送信も一度も行われていません。1.x を使用し、取引や請求が実行されたと思っていた場合、実際には実行されていません。CHANGELOG.mdをご覧ください。

2.x は npm で公開されており、npx bagos-mcp-server でインストールされるバージョンです。最新リリースをご覧ください。すべてのリリースには npm provenanceが付属しており、tarball がこのリポジトリおよびビルドに使用したコミットに暗号学的に証明されています。 1.x は npm で非推奨になっています。まだお使いの場合は、アップグレードしてください。

---

📦 掲載先

---

💡 問題と解決策

問題

資金を動かせるMCP サーバーは、AI アシスタントに署名鍵を渡すことになります。アシスタントが判断し、人間がその内容を知る頃には、取引はすでにオンチェーンで実行されています。プロトコルにはモデルに処理を一時停止させる仕組みがなく、誤解された指示ひとつで使われる金額を制限する仕組みもありません。

解決策

Bags は、特徴的なクリエイター手数料の分配機能を持つSolanaのトークンローンチパッドです。トークンの取引手数料は、ローンチやプロモーションを行った人々の間でオンチェーン上で分配され、いつでも請求できます。そのため、「このトークンから誰が収益を得るのか、いくら請求できるのか、そして請求する」という実際のワークフローが成立します。BagOSが自動化するのは、このワークフローです。

BagOSを使うと、AI アシスタントはBags／Solanaのトークンデータを読み取り、明示的な確認のうえで、ウォレットからスワップを実行したり、クリエイター手数料を請求したりできます。書き込み操作は設定しない限り無効で、メインネット専用です。また、書き込みツールの最初の呼び出しでは署名は行われず、プレビューと、発行時の正確な引数に対してのみ有効な使い捨てトークンが返されます。

🏗️ アーキテクチャと技術スタック

すべての書き込みは、次の手順を経由します。

token gate → spend caps → confirmation → simulate → sign → send → confirm

ツール	種別	内容
bags_heartbeat	読み取り	サーバーのステータスとウォレットの到達可能性
bags_get_token_analytics	読み取り	トークンミントの累計手数料データ
bags_get_creators	読み取り	累計手数料が多い上位トークン作成者
bags_get_trade_quote	読み取り	スワップの価格見積もり。取引は実行しません。
bags_get_claimable_fees	読み取り	ウォレットが現在請求可能な手数料
bags_get_partner_stats	読み取り	パートナー設定の請求統計
bags_get_token_claim_stats	読み取り	作成者ごとの請求総額 — 請求済み金額を含むロイヤリティ受取人一覧
bags_get_token_claim_events	読み取り	トークンの請求監査履歴。ページネーション対応
bags_get_token_creators	読み取り	トークンの手数料を共有する相手と、その分配比率
bags_resolve_launch_wallet	読み取り	ソーシャルハンドル（twitter/tiktok/kick/github）→ 手数料分配ウォレット
bags_authenticate	読み取り	Ed25519 署名でウォレットの所有権を検証
bags_prepare_token_metadata	制限付き	トークン情報とメタデータを作成します。トークンはローンチしません。
bags_execute_trade	書き込み	トークンをスワップします。署名して送信します。
bags_claim_fees	書き込み	作成者／LP の手数料を請求します。署名して送信します。

bags_prepare_token_metadata はミントを予約し、メタデータをアップロードします。ローンチを完了するには、さらに Meteora の手数料分配設定が必要です。その手数料請求者の分配はご自身で決める必要があるため、このサーバーでは推測して処理するのではなく、その手順を実装していません。bags.fm でローンチを完了してください。

---

🔐 書き込みツールと支出制御

書き込みは設定しない限り無効で、メインネット専用です。

Bags には devnet デプロイがありません。 API エンドポイントと Meteora／手数料分配のプログラム ID はすべてメインネット用です。それでも、このサーバーのデフォルトは devnet なので、未設定のインストールでは実際の資金を使えません。devnet で書き込みツールを呼び出すと、不可解なプログラムエラーではなく説明が返されます。

書き込みツールの最初の呼び出しでは、何も署名されません。プレビューと使い捨てトークンが返されます。

⚠️  CONFIRMATION REQUIRED — nothing has been signed or sent.

Action:  Swap 0.05 of So1111…1112
         for       EkJuyY…dBAGS
         expect    4823917722 (min 4679199990)
         slippage  3%
         network   🔴 MAINNET — real funds

Spend:   0.05 SOL
Caps:    0.1 SOL/tx · 0/1 SOL used this session

To execute, call bags_execute_trade again with the identical arguments plus:
  confirm: "kR3nT9xQm2vP"

このトークンはツール名と正確な引数のフィンガープリントです。そのため、0.01 SOL のスワップ用に発行されたトークンで 10 SOL のスワップを承認することはできません。有効期限は 5 分で、どのような結果になっても使用済みになるため、再利用できません。

成功すると、実際の署名とエクスプローラーへのリンクが返されます。着地しなかったトランザクションに対して成功メッセージを返すことはありません。

BAGS_ALLOW_UNCONFIRMED=true を設定すると、プレビューを省略できます。支出上限は引き続き適用されます。

上限が適用されるのは SOL のみです。 入力が別のトークンであるスワップは SOL に換算できないため、上限で制限できません。こうしたスワップはデフォルトで拒否されます。BAGS_ALLOW_UNCAPPED_TOKEN_SWAPS=true を設定すると許可でき、プレビューには上限のない取引であることが明示されます。

---

⛓️ ライブデプロイ

本番の書き込み経路で着地し、戻り値を信用するのではなく、チェーンから再取得した実際のトランザクションです。

署名	2kvu25xW…U5Dm
クラスター	devnet
スロット	484219564
ステータス	err: null
取得日	2026-08-16

npm run proof:devnet を実行して、ご自身で再現できます。このコマンドは、使い捨てのキーペアにフォーセットから資金を供給し、書き込みツールと同じシミュレーション → 署名 → 送信 → 確定の経路で送金を行い、その後チェーンから署名を再取得します。関数が success を返すのは主張にすぎません。エクスプローラーで開ける署名は証拠です。手順の詳細は DEMO.md をご覧ください。

---

📊 エンジニアリングの厳格性

418 件のテストがあります。支出上限と確認ステップを迂回するテストは、重要な保護機能です。ここへの変更はセキュリティ変更として扱ってください。上限チェック、確認チェック、小数点以下桁数の照会、支出記録処理を意図的に削除する変更を手作業で加えて検証したところ、いずれの場合もテストスイートが失敗しました。これは手作業による検証であり、自動化されたミューテーションテストの段階ではありません。このリポジトリには、再実行できるミューテーション設定はありません。

層	状態	詳細
実際のデフォルト経路	✅	ドキュメントに記載されているコマンドには、キルスイッチフラグがありません。USE_MOCK_DATA はデフォルトで オフ です。オンにすると、bags_get_claimable_fees ツールのみに影響し、そのツール自身の応答に ⚠️ [MOCK DATA ENABLED] が付加されます。ほかの 13 個のツールはこの設定を無視します。ライブ実行のレシートは DEMO.md を参照してください
コード品質	✅	ESLint と tsc --noEmit の両方で問題はありません
単体テスト	✅	Jest、418 件のテスト／19 個のスイート、ステートメント・分岐・関数・行を 100% カバーし、強制されています
重要度の高いテスト	✅	ミューテーションで検証した上限／確認の迂回テスト · 情報漏えい経路の回帰テスト（以前は API キーがツールの出力にそのまま含まれていました） · ネットワーク不一致時の拒否
セキュリティ	✅	CodeQL SAST · Dependabot SCA · 全履歴に対する gitleaks（fetch-depth: 0） · シークレットスキャンとプッシュ保護を有効化 · CI の npm audit は ラチェット として実行 — 下記参照
依存関係の負債	⚠️	6 件のアドバイザリ、重大なものは 0 件 — 90 件から減少しました。修正可能なものはすべて、バージョンを指定した overrides で解消しました（package.json を参照）。残っている 6 件の原因は 1 つ である bigint-buffer GHSA-3gc7-fjrx-p6mg で、@bagsfm/bags-sdk に至る依存関係の各階層で 1 件ずつ数えられています。修正済みの bigint-buffer は存在しません。インストールされている 1.1.5 は最新バージョンであり、脆弱性を含んでいます。CI は重大なアドバイザリと、.audit-baseline.json を超える件数の増加をブロックします。注： npm が overrides を適用するのはルートプロジェクトのみです。そのため、これらが保護するのはこのリポジトリと CI であり、公開パッケージの利用者ではありません。
CI	✅	4 段階（Quality → Security ∥ Test → Build）で、cancel-in-progress による同時実行制御を使用します。Node 22 と 24 のマトリックス、パッケージ化された成果物とエントリーポイントのチェックがあります
CD	✅	リリース → tarball の監査 → npm publish --provenance → 置き換えられたバージョンの非推奨化。別のワークフローでは OIDC 経由で server.json を MCP レジストリに送信します。どちらも CI スイート全体の成功を条件とします。1.0.0 は、含まれていた不具合への案内を付けて npm 上で非推奨になっています。
オンチェーンでの証明	✅	npm run proof:devnet は、本番の書き込み経路を通じて実際のトランザクションを送信し、チェーンから再取得します。2026-08-16 に記録：2kvu25xW…U5Dm、slot 484219564、err: null。誰でも再検証できます — DEMO.md を参照してください
コミュニティ基準	✅	行動規範 · コントリビューションガイド · セキュリティポリシー · issue と PR のテンプレート

E2E ブラウザーテストと Lighthouse の予算は意図的に設けていません。これは Web UI のない stdio／HTTP MCP サーバーであり、どちらも測定するものがないためです。最も近いエンドツーエンドのカバレッジは npm run demo です。これはライブ API に対する実際の MCP JSON-RPC 経由で、5 つの読み取りツール — bags_heartbeat、bags_get_creators、bags_get_trade_quote、bags_get_partner_stats、bags_authenticate — を実行します。残りの読み取りツールは単体テストのみでカバーされています。

---

🚀 はじめに

前提条件

Bags API キー が必要です。これだけで読み取り専用ツールを利用できます。取引や手数料の請求には、Solana のキーペアファイルとゲーティングトークンも必要です — 書き込みツールと支出管理 を参照してください。

書き込みの有効化

以下のすべてが設定されるまで、書き込みは無効のままです。

{
  "mcpServers": {
    "bagos": {
      "command": "npx",
      "args": ["-y", "bagos-mcp-server"],
      "env": {
        "BAGS_API_KEY": "your-key-here",
        "BAGS_NETWORK": "mainnet",
        "BAGS_KEYPAIR_PATH": "~/.config/bags/keypair.json",
        "BOS_TOKEN_MINT": "Feqmy64uNvK198MAWFC5ujRnzif6kM9wKonTX2t3BAGS",
        "BAGS_MAX_SOL_PER_TX": "0.1",
        "BAGS_MAX_SOL_PER_SESSION": "1.0"
      }
    }
  }
}

⚠️ BOS_TOKEN_MINT は現在、2つの役割を担っています。 ゲートが保有を要求する トークン（上記の $BOS）であると同時に、出力先が指定されていないスワップのデフォルトの 出力先ミントでもあります（ExecuteTrade.ts）。この2つには相反する性質が求められます。 ゲートでは保有するトークンが必要ですが、スワップの出力先には流動性のあるトークンが必要で、 $BOSにはほとんど流動性がありません。デフォルトに頼らず、bags_execute_trade では必ず outputMint を明示的に渡してください。これらを2つの変数に分けることは、既知の問題として 対応が追跡されています。

設定

変数	必須	デフォルト	備考
BAGS_API_KEY	はい	—	dev.bags.fm から取得
BAGS_NETWORK	いいえ	devnet	devnet または mainnet。書き込みには mainnet が必要です。
SOLANA_RPC_URL	いいえ	パブリッククラスタ RPC	BAGS_NETWORK と一致している必要があります。一致しない場合、サーバーは起動を拒否します
BAGS_KEYPAIR_PATH	書き込み時のみ	~/.config/bags/keypair.json	JSON バイト配列のキーペアファイル
BOS_TOKEN_MINT	書き込み時のみ	—	ゲート用トークンのミント
BOS_REQUIRED_BALANCE	いいえ	10000	ゲート用トークンの最小残高。0 にするとゲートが無効になり、どの残高でも通過します。数値以外の値を指定した場合、黙ってデフォルト値を使うのではなく、起動時に拒否されます。
BAGS_MAX_SOL_PER_TX	いいえ	0.1	1トランザクションあたりの支出上限
BAGS_MAX_SOL_PER_SESSION	いいえ	1.0	プロセスあたりの支出上限
BAGS_ALLOW_UNCONFIRMED	いいえ	false	確認手順を省略します
BAGS_ALLOW_UNCAPPED_TOKEN_SWAPS	いいえ	false	入力が SOL ではないスワップを許可します。上限は SOL 建てのため、これらを制限できません。
HELIUS_RPC_URL	いいえ	—	SOLANA_RPC_URL が未設定の場合にのみ読み込まれる別名
USE_MOCK_DATA	いいえ	false	true にすると、bags_get_claimable_fees は捏造された残高を返し、その旨を明記します。他のツールには影響しません。
BAGS_API_URL	いいえ	https://public-api-v2.bags.fm/api/v1	bags_authenticate が使用する Bags API のベース URL を上書きします。このツールはエンドポイントが送信する内容に署名するため、https を使い、bags.fm またはそのサブドメイン上にある必要があります。
BAGS_ALLOW_CUSTOM_API_URL	いいえ	false	true にすると、BAGS_API_URL に対する bags.fm の制限を解除します。自分が管理するサーバーでのみ使用してください。
BAGS_ENV_FILE	いいえ	—	読み込む env ファイルの絶対パス。MCP クライアントの作業ディレクトリは開いているプロジェクトによって異なるため、作業ディレクトリ内の .env が自動で読み込まれることはありません。
PORT	いいえ	3050	HTTP リスナーのポート。--http を指定して起動した場合にのみ読み込まれます。

---

🧪 テストと CI

npm ci
npm run ci            # lint + typecheck + tests with coverage
npm run dev           # stdio server with watch
npm run inspector     # MCP Inspector against the built server
npm run proof:devnet  # land a real devnet transaction through the write path

proof:devnet は、保存される使い捨てのキーペア（.proof/、gitignore 対象）を使用し、 必要に応じて devnet のフォーセットから資金を受け取り、書き込みツールと同じ シミュレーション／署名／送信／確認の手順で送金を実行します。その後、関数の戻り値を信頼せず、 チェーンから署名を再取得します。この最後の手順が重要です。関数が success を返すのは主張にすぎませんが、 エクスプローラーで開ける署名は証拠です。

---

📽️ デモ資料

• DEMO.md — Bags の mainnet API を実際に利用した実行結果： 7つのシナリオ、8つのステップ、ステップごとのレイテンシに加え、ネットワーク不一致ガードと、 書き込みを拒否するトークンゲートを確認できます。
• docs/examples.md — アシスタントに入力できるプロンプトと、それぞれが行うべき処理。
• docs/KNOWN_ISSUES.md — 現在の不具合とその理由、およびすでに原因として除外された項目を含みます。 未解決の注意事項についても、発見されるまで放置せず、ここで説明しています。

---

🛡️ セキュリティ

資金の入ったウォレットを接続する前に、SECURITY.md をお読みください。

概要：秘密鍵はディスクから読み込まれて署名に使用されますが、ログに記録されたり、どこかに送信されたり、エラーメッセージに含まれたりすることはありません。ツールのエラーで返されるのはメッセージのみで、スタックトレースはなく、秘密鍵のような文字列はマスキングされます。起動レポートでは RPC URL の認証情報が削除されます。RPC エンドポイントのクラスターと BAGS_NETWORK が一致しない場合、devnet の表示のまま mainnet のトランザクションに署名することがないよう、サーバーは起動を拒否します。

同じルールが、Bags API キーにも適用されるようになりました。bags_authenticate はキーを ~/.config/bags/credentials.json に書き込み、末尾の 4 文字だけを表示します。以前はキー全体が出力されていたため、有効な認証情報がアシスタントのコンテキストと、その後に続くすべてのトランスクリプトに公開されていました。この変更より前のバージョンで bags_authenticate を実行した場合は、dev.bags.fm でキーをローテーションしてください。

これらの制御に関する既知の制限

SECURITY.md に記載するだけでなく、ここでも明記しておくべき点が 2 つあります。

• HTTP モードには認証がありません。 --http を指定して起動すると、サーバーは CORS を許可し、認証なしで 0.0.0.0 をリッスンします。そのため、ポートにアクセスできる呼び出し元なら誰でも書き込みツールを実行でき、支出カウンターも共有されます。資金の入ったウォレットでは HTTP モードを実行しないでください。 stdio がデフォルトであり、このプロジェクトが推奨する唯一のトランスポートです。そのため、Smithery の掲載もホスト型ではなく stdio のみとなっています。
• セッション上限では、結果が不明な取引もカウントされます。 送信後に確認がタイムアウトした場合、支出はカウントされます（取引が成立する可能性があります）。また、エラーには署名が含まれます。エクスプローラーで確認してから、サーバーを再起動してカウンターをリセットしてください。

脆弱性は GitHub security advisories から報告してください。

---

📄 ライセンス

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