Prolific Mcp Server

prolific-mcp

LLM エージェントと Prolific のパブリック API をつなぐ Model Context Protocol サーバーです。FastMCP で構築されています。

公式 MCP Registry に掲載されており、Claude Desktop、Cursor、Claude Code など、MCP 対応クライアントから見つけられます。

警告

publish_study は実際のお金を使います。 Prolific で研究を公開すると、参加者はすぐに開始でき、参加者の作業に対して料金が発生します。LLM による呼び出しは、実際の支出として扱ってください。ツール呼び出しを承認する前に、研究の下書きと報酬を確認してください。サンドボックスモードはありません。同じエンドポイントが本番環境で使用されます。

できること

LLM が研究者による Prolific での調査の設計と開始を支援できるよう、少数のツールを公開します。

ツール	Prolific エンドポイント
get_filters	GET /api/v1/filters/
get_filter_sets	GET /api/v1/filter-sets/
create_filter_set	POST /api/v1/filter-sets/
get_eligibility_count	POST /api/v1/eligibility-count/
list_workspaces	GET /api/v1/workspaces/
list_projects	GET /api/v1/workspaces/{workspace_id}/projects/
list_studies	GET /api/v1/studies/
view_study	GET /api/v1/studies/{id}/
create_study	POST /api/v1/studies/
publish_study	POST /api/v1/studies/{id}/transition/
pause_study	POST /api/v1/studies/{id}/transition/
resume_study	POST /api/v1/studies/{id}/transition/
stop_study	POST /api/v1/studies/{id}/transition/
list_submissions	GET /api/v1/studies/{id}/submissions/
get_submission_counts	GET /api/v1/studies/{id}/submissions/counts/
bulk_approve_submissions	POST /api/v1/submissions/bulk-approve/
list_collections	GET /api/v1/data-collection/collections
view_collection	GET /api/v1/data-collection/collections/{id}
preview_collection	(Prolific エンドポイントなし — 決定的なアプリのプレビュー URL を返します)
create_collection	POST /api/v1/data-collection/collections
update_collection	PUT /api/v1/data-collection/collections/{id}/
export_collection	POST /api/v1/data-collection/collections/{id}/export
get_collection_export_status	GET /api/v1/data-collection/collections/{id}/export/{export_id}
export_study_demographics	POST /api/v1/studies/{id}/demographic-export/
list_webhook_event_types	GET /api/v1/hooks/event-types/
ensure_webhook_secret	GET /api/v1/hooks/secrets/（存在確認のみ — 以下の注記を参照）
create_webhook_secret	POST /api/v1/hooks/secrets/
create_webhook_subscription	POST /api/v1/hooks/subscriptions/ + 確認
list_webhook_subscriptions	GET /api/v1/hooks/subscriptions
update_webhook_subscription	PATCH /api/v1/hooks/subscriptions/{id}/
delete_webhook_subscription	DELETE /api/v1/hooks/subscriptions/{id}/
list_webhook_events	GET /api/v1/hooks/subscriptions/{id}/events/
get_capabilities	(ローカル — Prolific エンドポイントなし。サーバーのバージョン、対象 API URL、登録済みツールを報告します)

メモ

Webhook シークレットの取り扱いは意図的に限定しています。 create_webhook_secret は、このリポジトリで機密情報を返す唯一のツールです。また、ワークスペースで初めて作成するときに一度だけ返します。既存のシークレットの値を一覧表示または再取得するツールはありません。再取得できると、その値が読み取るたびに LLM のコンテキストに含まれてしまうためです。ワークスペースにすでにシークレットがあり、その値をもう一度確認する必要がある場合（たとえば、受信側の設定を変更するとき）は、MCP ではなく CLI で prolific hook secrets -w <workspace_id> を実行してください。

要件

• Python 3.11+
• Prolific API トークン（https://app.prolific.com で作成してください）

クイックスタート

uv を使って PyPI からインストールし、実行します。

export PROLIFIC_TOKEN=your_token_here
uvx prolific-mcp

または、チェックアウトから実行します。

uv sync
export PROLIFIC_TOKEN=your_token_here
uv run prolific-mcp

サーバーはデフォルトで stdio を使用し、MCP クライアント（Claude Desktop、Cursor など）から起動することを想定しています。

ローカル開発（HTTP モード）

stdio ではプロセスの所有権がクライアントにあるため、サーバーのログが表示されません。ローカルで反復開発する場合は、代わりにストリーミング可能な HTTP 経由で実行すると、ログがターミナルにストリーミングされます。

PROLIFIC_TOKEN=your_token_here uv run prolific-mcp --http
# server listens on http://127.0.0.1:8765/mcp

# register it with Claude Code in another terminal:
claude mcp add prolific --transport http http://127.0.0.1:8765/mcp

8765 が使用中の場合は、--host / --port でホストやポートを変更してください。

環境変数

変数	必須	デフォルト	説明
PROLIFIC_TOKEN	はい	—	Prolific API トークン。Authorization: Token … として送信されます
PROLIFIC_URL	いいえ	https://api.prolific.com	Prolific API のベース URL
PROLIFIC_APPLICATION_URL	いいえ	https://app.prolific.com	Prolific Web アプリのベース URL。preview_collection のリンクに使用されます

MCP クライアントでの使用

Claude Desktop

各 GitHub リリースには、プラットフォームごとの .mcpb バンドル（darwin-arm64、darwin-x86_64、linux-x86_64、windows-x86_64）が添付されています。お使いのプラットフォーム用のファイルをダウンロードして開くと、Claude Desktop にインストールダイアログが表示され、PROLIFIC_TOKEN の入力を求められます。

手動で設定する場合は、Claude Desktop の設定にサーバーを追加します。

{
  "mcpServers": {
    "prolific": {
      "command": "uvx",
      "args": ["prolific-mcp"],
      "env": { "PROLIFIC_TOKEN": "your_token_here" }
    }
  }
}

Claude Code

claude mcp add prolific \
  -e PROLIFIC_TOKEN=your_token_here \
  -- uvx prolific-mcp

特定のバージョンを固定するには、uvx prolific-mcp を uvx prolific-mcp==<version> に置き換えます。

Codex CLI

~/.codex/config.toml に追加します。

[mcp_servers.prolific]
command = "uvx"
args = ["prolific-mcp"]
env = { PROLIFIC_TOKEN = "your_token_here" }

Codex を再起動するか、新しいセッションを開始すると設定が反映されます。

Cursor およびその他の MCP 対応クライアント

ほとんどのクライアントは、上記の Claude Desktop の JSON と同じ command／args／env の形式を受け付けます。

開発

uv sync
uv run pytest          # tests
uv run mypy            # type-check
uv run ruff check .    # lint
uv run ruff format .   # format

Docker

docker build -t mcp/prolific .
docker run -i --rm -e PROLIFIC_TOKEN=$PROLIFIC_TOKEN mcp/prolific