argo-mcp

Argo MCP Server

Model Context Protocol を介して、AI アシスタントを Argo のキャンペーンに接続します。設定すると、AI アシスタントはチャットインターフェースからキャンペーンのロアを読み書きしたり、キャラクターの詳細を調べたり、Argo のデータを直接操作したりできます。

対応クライアント：Claude Code、Claude Desktop、OpenAI Codex、VS Code（1.103 以降）、および MCP 対応ホスト。

ワンクリックインストール

どちらかのボタンをクリックすると、この設定を含む vscode:mcp/install URL がエディターに渡されます。

{ "type": "http", "url": "https://mcp.argo.games/mcp" }

VS Code はユーザーレベルの mcp.json にエントリーを保存し、初回接続時に Argo 認可サーバーに対して Dynamic Client Registration を介した OAuth をネゴシエートします。URL にトークンは埋め込まれません。VS Code は取得したアクセストークンとリフレッシュトークンを OS のキーチェーンに保存します。

Linux／Flatpak／Snap に関する注意： ボタンをクリックしても VS Code が開かない場合、vscode: URL ハンドラーが登録されていません。これは次の環境でよく発生します。

• Flatpak／Snap 版 VS Code — サンドボックスによってインストール先がホストから隔離されるため、ホストのブラウザーからプロトコルハンドラーを見つけられません。
• tarball／手動インストール — update-desktop-database を実行する postinst フックがありません。xdg-mime default code.desktop x-scheme-handler/vscode を一度実行するか、以下の手動での代替手順を使用してください。

手動での代替手順：以下の VS Code（ワンクリック、推奨） セクションにある JSON をコピーし、VS Code の mcp.json 設定に貼り付けます。

同じインストールボタンは、Argo のインストールページ https://app.argo.games/docs/mcp/install にも表示されます。

---

前提条件

• Node.js 20 以降
• キャンペーンが 1 つ以上ある Argo アカウント
• ゲームマスターが OAuth2 の同意フローを介して AI アシスタントを認可する必要があります（トークンの取得を参照）

---

クイックスタート

Argo MCP サーバーを使用する方法は 3 つあります。クライアントに合った方法を選んでください。

ChatGPT（リモート）

ホストされたエンドポイントを使用してください。npx パッケージはインストールしないでください。次の MCP サーバー URL を ChatGPT に追加します。

https://mcp.argo.games/mcp

ChatGPT は初回接続時に、動的クライアント登録を介した OAuth の手順を案内します。

ローカル MCP クライアント（Claude Code、Claude Desktop、Codex など）— 推奨

MCP クライアントを実行するマシンで、一度サインインします。

npx -y argo-mcp auth login

このコマンドは同意 URL を表示しますが、何も開きません。同意ページからアクセストークン（および任意でリフレッシュトークン）をコピーして貼り付けるよう求めます。トークンはローカルに保存されます。

• Windows：%APPDATA%\argo-mcp\tokens.json
• macOS：~/Library/Application Support/argo-mcp/tokens.json
• Linux：${XDG_CONFIG_HOME:-~/.config}/argo-mcp/tokens.json

次に、環境変数を指定せずに MCP サーバーを設定します。

{
  "mcpServers": {
    "argo": { "command": "npx", "args": ["-y", "argo-mcp"] }
  }
}

その他の認証コマンド：

npx -y argo-mcp auth status   # show whether you are signed in
npx -y argo-mcp auth logout   # forget locally stored tokens

ローカルの stdio モードでは OAuth Dynamic Client Registration を使用しません。DCR はホストされた HTTP サーバー https://mcp.argo.games でのみ使用されます。

上級者向け — 環境変数

CI、Docker、または明示的な環境変数設定を希望する場合は、auth login を省略し、トークンを直接渡すことができます。OAUTH_TOKEN は常にローカルトークンストアより優先されます。

{
  "mcpServers": {
    "argo": {
      "command": "npx",
      "args": ["-y", "argo-mcp"],
      "env": {
        "OAUTH_TOKEN": "<your-access-token>",
        "REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

---

ソースからビルドする（コントリビューター向け）

git clone https://github.com/Argo-RPG-Platform/MCP.git argo-mcp
cd argo-mcp
npm install
npm run build

---

トークンの取得

MCP サーバーは、特定のキャンペーン群に紐づいた OAuth2 アクセストークンを使用して Argo と認証します。トークンは Argo の同意フローを通じて取得します。

1. ブラウザーで https://app.argo.games/oauth2/mcp-connect を開きます。
2. AI アシスタントにアクセスさせるキャンペーンと、権限レベル（読み取り、または読み取り＋書き込み）を選択します。
3. Authorize をクリックします。2 つのトークンが表示されたページにリダイレクトされます。
   • Access token — OAUTH_TOKEN として設定します
   • Refresh token — REFRESH_TOKEN として設定します（推奨。アクセストークンが約 1 時間後に期限切れになったときに自動更新できます）

どちらのトークンもパスワードと同様に扱ってください。キャンペーンの連携ページから、いつでもトークンを取り消せます。

---

設定

VS Code（ワンクリック、推奨）

この README の上部にあるインストールボタンを使うか、以下を .vscode/mcp.json（ワークスペース単位）またはユーザーレベルの MCP 設定に貼り付けます。

{
  "servers": {
    "argo": {
      "type": "http",
      "url": "https://mcp.argo.games/mcp"
    }
  }
}

初回接続時、VS Code は Dynamic Client Registration を通じて OAuth を自動的に処理します。OAUTH_TOKEN や REFRESH_TOKEN を設定する必要はありません。VS Code はトークンを OS のキーチェーンに保存します。

Claude Code

CLI でサーバーを追加します。

claude mcp add argo \
  --command node \
  --args /absolute/path/to/argo-mcp/dist/index.js \
  --env OAUTH_TOKEN=<your-access-token> \
  --env REFRESH_TOKEN=<your-refresh-token>

または、プロジェクトの .claude/settings.json に手動で追加します。

{
  "mcpServers": {
    "argo": {
      "command": "node",
      "args": ["/absolute/path/to/argo-mcp/dist/index.js"],
      "env": {
        "OAUTH_TOKEN": "<your-access-token>",
        "REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

Claude Desktop

Claude Desktop の設定ファイルを編集します。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "argo": {
      "command": "node",
      "args": ["/absolute/path/to/argo-mcp/dist/index.js"],
      "env": {
        "OAUTH_TOKEN": "<your-access-token>",
        "REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

保存後、Claude Desktop を再起動してください。

OpenAI Codex

Codex の MCP 設定にサーバーを追加します。

{
  "mcpServers": {
    "argo": {
      "command": "node",
      "args": ["/absolute/path/to/argo-mcp/dist/index.js"],
      "env": {
        "OAUTH_TOKEN": "<your-access-token>",
        "REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

ChatGPT App の申請

ホスト型 ChatGPT アプリの画面向けに、このリポジトリでは MCP ドメイン上で OAuth ディスカバリー、動的クライアント登録、ドメイン検証のエンドポイントを公開しています。申請チェックリストと必要な環境変数については、CHATGPT_APP_SUBMISSION.md をご覧ください。

.env ファイルの使用（ローカル開発）

argo-mcp ディレクトリに .env ファイルを作成します。

OAUTH_TOKEN=<your-access-token>
REFRESH_TOKEN=<your-refresh-token>

その後、直接実行します。

npm run dev       # hot-reload via tsx
# or
npm start         # compiled dist/

---

事前構築済みエージェントスキル

MCP に接続したら、argo-agent-skills プラグインをインストールすると、以下のツールを連携させる、すぐに使えるゲームマスター向けワークフロー（セッションの準備、セッション後の振り返り、NPC の生成、ガイド付き MCP セットアップなど）を利用できます。同じスキルソースには、Claude（Code ＋ Claude.ai）と OpenAI 互換クライアント（Codex、ChatGPT）向けのパッケージも含まれています。

Claude Code:

/plugin marketplace add Argo-RPG-Platform/argo-agent-skills
/plugin install argo-gm-pack@argo

Claude.ai / Codex / ChatGPT: 最新リリースから対象ごとの zip ファイルをダウンロードし、そのリポジトリの README にあるアップロード手順に従ってください。

スキルの一覧、例、および独自のスキルを作成するためのガイダンスについては、Argo Skills のドキュメントをご覧ください。

---

利用可能なツール

このサーバーは、キャンペーン、mnemons、セッション、ギルド、友達、Argo コミュニティフォーラムに関するツールを公開しています。

キャンペーン

• list_campaigns（campaign.read）アクセス可能なキャンペーンとそのアクセスレベルを一覧表示します
• get_campaign（campaign.read）キャンペーンの詳細を取得します
• create_campaign（campaign.create）新しいキャンペーンを作成します
• update_campaign（campaign.write）キャンペーン名または説明を更新します
• list_co_gms（campaign.read）アシスタント GM を一覧表示します
• add_co_gm（campaign.write）アシスタント GM を追加します
• remove_co_gm（campaign.write）アシスタント GM を削除します

Mnemons

• describe_mnemon_types は、サポートされている mnemon の種類、関係ラベル、コンテンツブロックのルールを一覧表示します
• list_mnemons（campaign.read）は、キャンペーンの mnemon エントリを一覧表示します
• get_mnemon（campaign.read）は、mnemon エントリの全内容を取得します
• list_mnemon_relationships（campaign.read）は、リンクされたエントリと関係エッジを一覧表示します
• create_*_mnemons（campaign.write）は、NPC、Location、Quest、Lore、Archive、Journal、SessionSummary、Player、Custom の各エントリについて、種類別の mnemon エントリを作成します
• update_*_mnemons（campaign.write）は、これらの mnemon エントリの種類について、種類別フィールド／メタフィールドを更新します。quest ツールでは、クエストの目標、報酬チップ、背景、GM メモも書き込みます
• set_quest_objective_state（campaign.write）は、ID を指定してクエストの目標を達成済みにする、失敗にする、または再開します
• update_mnemons_content（campaign.write）は、mnemon のコンテンツブロックを編集します
• create_mnemon_relationship（campaign.write）は、エントリ間の関係を作成します
• delete_mnemon_relationship（campaign.write）は、ID を指定して関係を削除します

Sessions

• create_session（campaign.write）は、キャンペーンのセッションを予定に登録します
• list_sessions（campaign.read）は、キャンペーンと月を指定してセッションを一覧表示します
• get_session（campaign.read）は、単一のセッションを取得します
• update_session（campaign.write）は、セッションの予定またはテキストを更新します

Guilds

• list_guilds（guild.read）は、現在のユーザーが所属するギルドを一覧表示します
• get_guild（guild.read）は、ギルドの詳細を取得します
• list_guild_members（guild.read）は、ギルドのメンバーを一覧表示します
• add_campaign_to_guild（guild.write）は、キャンペーンをギルドにリンクします
• invite_guild_member（guild.admin）は、ギルドメンバーを招待します
• remove_guild_member（guild.admin）は、ギルドメンバーを削除します
• set_guild_member_role（guild.admin）は、ギルドメンバーのロールを変更します
• add_guild_calendar_event（guild.admin）は、ギルドのカレンダーイベントを追加します

Friends

• list_friends（friends.read）は、承認済みの友達を一覧表示します
• list_sent_friend_requests（friends.read）は、送信済みの保留中リクエストを一覧表示します
• list_received_friend_requests（friends.read）は、受信した保留中リクエストを一覧表示します
• send_friend_request（friends.write）は、友達リクエストを送信します
• accept_friend_request（friends.write）は、リクエストを承認します
• reject_friend_request（friends.write）は、リクエストを拒否します
• cancel_friend_request（friends.write）は、送信済みのリクエストを取り消します

キャンペーンやギルドに誰かを招待するには、invite_guild_member または send_friend_request を使用してください。MCP の機能では、既存の Argo コンテキスト外のメールアドレスにはメールを送信できません。

Forum

• forum_list_categories（forum.read）は、フォーラムのカテゴリを一覧表示します
• forum_list_topics（forum.read）は、カテゴリ内のトピックを一覧表示します
• forum_get_latest_topics（forum.read）は、最近のフォーラムの活動を一覧表示します
• forum_read_topic（forum.read）は、トピックのスレッドを読み込みます
• forum_search（forum.read）は、フォーラムのコンテンツを検索します
• forum_get_user_posts（forum.read）は、現在のユーザーのトピックを一覧表示します
• forum_get_notifications（forum.read）は、現在のユーザーへの通知を一覧表示します
• forum_create_topic（forum.write）は、community.argo.games に新しいトピックを作成します
• forum_reply（forum.write）は、community.argo.games の既存のトピックに返信します

キャンペーンに紐づく多くのツールは、campaignId を受け付けます。キャンペーンの ID は、Argo のキャンペーン URL から確認するか、GM に尋ねてください。

---

トークンの更新

アクセストークンの有効期限は約 1 時間です。REFRESH_TOKEN が設定されている場合、最初のリクエストが 401 を返した際に、サーバーが新しいアクセストークンを自動的に取得し、透過的に再試行します。操作は不要です。

リフレッシュトークンが設定されておらず、アクセストークンの有効期限が切れた場合、ツールは次のメッセージを返します。

トークンの有効期限が切れました — https://app.argo.games/oauth2/mcp-connect で再度同意してください

この URL で同意フローを再実行し、新しいトークンを取得してください。

---

アクセスの取り消し

AI アシスタントをキャンペーンから切断するには、Argo WebApp のキャンペーン連携ページで許可を取り消してください。アクセストークンとリフレッシュトークンは、どちらも直ちに無効になります。

---

環境変数

変数	必須	説明
OAUTH_TOKEN	auth login でサインインしていない場合	同意フローで発行された OAuth2 アクセストークン
REFRESH_TOKEN	推奨	OAuth2 リフレッシュトークン。自動更新が可能になります
ARGO_API_BASE	いいえ	API のベース URL を上書きします（デフォルト：https://api.argo.games）
ARGO_MCP_TOKEN_PATH	いいえ	auth login が使用するローカルトークンファイルのパスを上書きします

---

プライバシーポリシー

ポリシー全文：https://argo.games/privacy

Argo MCP サーバーが取り扱う情報：

• 収集するデータ。 Argo 認可サーバー（oauth.argo.games）が発行する OAuth アクセストークンとリフレッシュトークン、ツール呼び出しを通じてやり取りされるキャンペーン、mnemon、ギルド、フォーラム、フレンドのペイロード、レート制限と不正利用対策のための標準的な HTTP メタデータ（IP、ユーザーエージェント）。
• 利用目的。 ツール呼び出しは、認証済みユーザーに代わって Argo WebAPI（api.argo.games）にプロキシされます。MCP セッションの存続期間中、トークンはプロセス内にキャッシュされます。そのため、後続のリクエストで Authorization を省略するクライアント（Claude Code で確認されている挙動）も引き続き動作します。
• 保存と保持期間。 セッショントークンのキャッシュはメモリ内にのみ保持され、30 分間操作がないと破棄されます。MCP サーバーはユーザーコンテンツ（mnemon、キャンペーン、フォーラム投稿）を保存しません。これらは WebAPI に転送された後、破棄されます。ログに保持されるのはリクエストのメタデータのみで、ペイロードの内容は含まれません。
• 第三者との共有。 リクエストは Argo WebAPI と（OAuth フロー中は）Argo 認可サーバーにのみ転送されます。このサーバーから他の第三者にリクエストデータが提供されることはありません。
• お問い合わせ先。 プライバシーに関するお問い合わせ：[email protected]。セキュリティ上の問題の報告については、Argo GitHub 組織の SECURITY ポリシーをご覧ください。

上記リンク先のホストされたプライバシーポリシーが正式なものです。WebAPI と WebApp を含む Argo プラットフォーム全体を対象としています。

---

ライセンス

MIT — LICENSE をご覧ください。