Social Champ

Social Champ MCP サーバー

Social Champ プラットフォーム用の Model Context Protocol（MCP）サーバーです。Claude Desktop、Claude Code、Cursor など、MCP 対応 AI クライアントに Social Champ の全ツールカタログを公開します。投稿のスケジュール設定と管理、接続済みチャンネルとワークスペースの管理、ラベル、キュー、再利用、共有可能なカレンダー、代理店の承認ワークフロー、AI コンテンツウィザードを利用できます。

ツール

このサーバーは、Social Champ の最新 MCP ツールカタログを反映しています。チャンネルは接続済みのソーシャルプロフィールで、ワークスペースはチャンネルと共有可能なカレンダーをまとめるものです。ツール定義は、最新サーバーのカタログのスナップショットである tools.schema.json から生成されるため、ツール一式、引数名、説明はホスト型サーバーと一致します。

ツールはドメインごとに分類されています。

• 投稿：作成、更新、削除、一括スケジュール設定、閲覧、キューの並べ替え、Instagram の最初のコメント設定。
• チャンネル：一覧表示、フィルター、個別取得、場所の検索。
• ワークスペース：一覧表示。
• カレンダー：表示オプション、アプリ内 URL、共有可能なカレンダーの作成、一覧表示、更新、削除。
• キュー：一時停止、再開、クリア。
• ラベル：一覧表示、作成、適用、削除、一括適用。
• 再利用：コレクションの一覧表示、投稿の再利用。
• 代理店ワークフロー：承認待ちの一覧表示、承認、却下、承認者へのリマインド、一括削除。
• AI ウィザード：投稿の生成、ハッシュタグの提案、書き換え、画像の生成。

各ツールには ToolAnnotations が付与されているため、クライアントは適切な確認動作を適用できます。読み取り専用ツールには readOnlyHint=True が設定されています。破壊的なツール（delete_post、delete_shareable_calendar、bulk_delete、queue_clear）には destructiveHint=True が設定されています。代理店ツールには、呼び出し元のトークンに manage_team スコープも必要です。この要件は各ツールの説明に記載されています。

必須引数とスコープを含むツールごとの一覧は、こちらの tools.schema.json または認証リポジトリの api/mcp/IMPLEMENTED.md を参照してください。

要件

• Python 3.10 以降。
• Social Champ API キーまたは OAuth2 アクセストークン。どちらも Bearer トークンとして送信されます。 公開ツールで使用する OAuth2 スコープは read_profile と manage_post です。代理店ツール（承認、リマインダー、一括削除）には manage_team も必要です。

インストール

uv を使って、PATH 上のコマンドとしてインストールします。

uv tool install socialchamp-mcp

その後、シェルから socialchamp-mcp が見つからない場合は、uv tool update-shell を実行して新しいターミナルを開いてください。インストールせずに実行するには、この README で socialchamp-mcp と記載されている箇所で uvx socialchamp-mcp を使用してください。

pip を使用する場合：

pip install socialchamp-mcp

ソースからインストールする場合：

git clone https://github.com/socialchamp/socialchamp-mcp.git
cd socialchamp-mcp
pip install -e ".[dev]"

設定

環境変数で設定します。

変数	必須	デフォルト	用途
SOCIALCHAMP_API_KEY	はい	なし	Bearer トークン：Social Champ API キーまたは OAuth2 アクセストークン
SOCIALCHAMP_API_BASE_URL	いいえ	https://mcp.socialchamp.com/mcp	ホスト型 MCP エンドポイントを上書きします（例：ローカルのテストサーバー）
SOCIALCHAMP_TIMEOUT	いいえ	30	リクエストのタイムアウト（秒）
SOCIALCHAMP_TRANSPORT	いいえ	stdio	stdio、sse、または streamable-http
SOCIALCHAMP_MCP_PROTOCOL_VERSION	いいえ	2025-06-18	initialize 時に送信する MCP プロトコルのバージョン

このサーバーは環境変数のみを読み込み、.env ファイルを自動で読み込みません。 ローカルで使用する場合は、変数を .env ファイルに記述し（ソースのチェックアウトでは .env.example をコピーし、それ以外ではエディターで SOCIALCHAMP_API_KEY=... の行を含むファイルを作成してください）、自分だけが読み取れるようにしてから、サーバーの起動前にシェルへ読み込んでください。

chmod 600 .env
set -a; . ./.env; set +a

使用後は unset SOCIALCHAMP_API_KEY を実行してください。.env をコミットしないでください。

MCP クライアントの設定

Claude Desktop

サーバーを claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "socialchamp": {
      "command": "socialchamp-mcp",
      "env": {
        "SOCIALCHAMP_API_KEY": "your-api-key"
      }
    }
  }
}

コンソールスクリプトが PATH 上にない場合は、"command": "python" と "args": ["-m", "socialchamp_mcp"] を使用してください。

Claude Code

最も簡単なのは、API キー不要のホステッドサーバーを使う方法です。代わりに、ブラウザーで Social Champ にサインインします。

claude mcp add --scope user --transport http SocialChamp https://mcp.socialchamp.com/mcp

次に、Claude Code で /mcp を実行し、SocialChamp を選択してサインインします。--scope user を指定すると、Claude Code を開くすべてのフォルダーでサーバーを利用できます。指定しない場合は、 コマンドを実行したフォルダーでのみ利用できます。サインインで付与される権限は read_profile と manage_post です。承認やその他のエージェンシーツールには manage_team が必要なので、 それらが必要な場合は、その権限を持つ API キーを使用してください。

代わりに API キーを使ってこのパッケージをローカルで実行するには、キーを表示したり シェル履歴に保存したりせずに読み込みます。

printf 'Social Champ API key: '; read -rs SOCIALCHAMP_API_KEY; printf '\n'
claude mcp add --scope user SocialChamp --env SOCIALCHAMP_API_KEY="$SOCIALCHAMP_API_KEY" -- socialchamp-mcp
unset SOCIALCHAMP_API_KEY

uvx を使用する場合は、2 行目の末尾を -- uvx socialchamp-mcp にしてください。Claude Code は、ほかのサーバーの環境変数と同様に、キーを独自の設定（~/.claude.json）に保持します。 また、コマンドの実行中は、そのキーがマシン上のほかのプロセスから見える状態になります。 共有マシンでは、ホステッドサインインをおすすめします。

Claude Code 用カレンダーペイン

Claude Code をお使いですか？ Social Champ calendar mod を使うと、このサーバーにサイドペインが追加されます。週、月、日の表示、失敗した投稿と承認、 下書き、Claude で作成した新しい投稿を確認できます。変更内容はすべて先に表示され、 「はい」を押した後にのみ送信されます。また、チャットから Claude が Social Champ の内容を 変更する前にも確認を求めます。

claude plugin marketplace add SocialChamp/socialchamp-claude-mods
claude plugin install socialchamp-calendar@socialchamp-mods

Claude Code 2.1.293 以降が必要です。/reload-plugins を実行し、その後 /socialchamp-calendar を実行してください。この mod は、上記のとおり SocialChamp という 名前でサーバーを探すため、設定は不要です。別の名前で追加した場合は、 /plugin configure socialchamp-calendar@socialchamp-mods を一度実行して、その名前を設定してください。 自動モードでは、ペインが開いた後に、 mod の README にある権限ルール（mcp__<server name>__<tool>。名前に含まれるスペースはアンダースコアに置き換えます） を追加してください。

HTTP 経由での実行

デフォルトのトランスポートは stdio で、Claude Desktop と Claude Code が使用します。 代わりに HTTP 経由で実行するには、SOCIALCHAMP_TRANSPORT を設定します。

printf 'Social Champ API key: '; read -rs SOCIALCHAMP_API_KEY; printf '\n'
export SOCIALCHAMP_API_KEY
SOCIALCHAMP_TRANSPORT=streamable-http socialchamp-mcp

sse もサポートされています。生成された HTTP エンドポイントをクライアントに指定してください。

実際の API へのマッピング

ツールは JSON-RPC 経由で、ホステッドの Social Champ MCP サーバーにリクエストを転送します。 稼働中のツールは認証バックエンド（api/mcp/handlers.ts）に実装されており、外部 API キーから 直接呼び出せない内部サービスルートを通じて champ に接続します。そのため、ユーザーのトークンで 完全なカタログにアクセスできるのは、ホステッド MCP サーバーのみです。HTTP 呼び出しを行う ファイルは src/socialchamp_mcp/client.py のみで、SOCIALCHAMP_API_BASE_URL に指定された エンドポイントに対して JSON-RPC 2.0（initialize、tools/list、tools/call）を使用します。

src/socialchamp_mcp/server.py は、稼働中サーバーの api/mcp/tools.ts のスナップショットである tools.schema.json から生成されます。稼働中のカタログを変更した後に更新するには、次の手順を実行します。

1. 認証リポジトリからスナップショットを tools.schema.json に再エクスポートします（稼働中の tools.ts 配列を JSON として出力します）。
2. python scripts/generate_server.py を実行します。

ベース URL と Bearer 認証は、Social Champ の 認証ガイドで確認されています。

プロジェクト構成

socialchamp-mcp/
├── tools.schema.json        # snapshot of the live tool catalog (source for codegen)
├── scripts/
│   └── generate_server.py   # regenerates server.py from tools.schema.json
├── src/
│   └── socialchamp_mcp/
│       ├── __init__.py
│       ├── __main__.py      # python -m socialchamp_mcp
│       ├── config.py        # settings from the environment
│       ├── client.py        # the only file that makes HTTP calls (JSON-RPC)
│       └── server.py        # GENERATED: FastMCP instance and tool definitions
└── tests/
    └── test_server.py

ツールの追加

ツールは手書きではなく、生成されます。認証リポジトリの稼働中の api/mcp/tools.ts にツールを追加し、 tools.schema.json を更新してから、python scripts/generate_server.py を実行します。 ジェネレーターは各ツールを call_tool に転送する @mcp.tool 関数にマッピングし、 ToolAnnotations のプリセット（READ、WRITE、UPDATE、DESTRUCTIVE）を選び、 ツールの説明から docstring を作成します。破壊的操作または読み取り専用のツールを追加する場合は、 scripts/generate_server.py の分類セットも更新してください。

チェックリストの全項目については、CONTRIBUTING.md を参照してください。

開発

pip install -e ".[dev]"
pytest

stdio 経由でサーバーが起動することを確認するには、次を実行します。

SOCIALCHAMP_API_KEY=dummy SOCIALCHAMP_TIMEOUT=5 socialchamp-mcp

終了せずに、標準入力からの入力を待機します。Ctrl+C で停止してください。

セキュリティ

• API キーは環境から読み込まれ、Bearer トークンとして送信されます。このサーバーによってログに記録されたり、ディスクに書き込まれたりすることはありません。
• キーは .env またはクライアントのシークレットストアに保管してください。コミットしないでください。また、シェルの履歴に残るコマンドラインには入力しないでください。.gitignore では .env が除外されています。OAuth でサインインする場合（ホスト型サーバー）、キーは不要です。
• ツールには読み取り専用、書き込み、破壊的のいずれかが注釈されています。破壊的なツール（delete_post、delete_shareable_calendar、bulk_delete、queue_clear）には destructiveHint=True が設定されているため、クライアントは実行前に確認できます。
• Agency ツールを呼び出すには、呼び出し元のトークンに manage_team スコープが必要です。このスコープのないトークンでは呼び出せません。
• トークンのスコープは、ツールが必要とする権限だけにしてください。トークンが漏えいした場合は、Social Champ アカウントでローテーションしてください。

ライセンス

MIT。LICENSE をご覧ください。