Prolific Mcp Server

prolific-mcp

A Model Context Protocol server bridging LLM agents to the Prolific public API. Built with FastMCP.

Listed on the official MCP Registry — discoverable from Claude Desktop, Cursor, Claude Code, and other MCP-aware clients.

Warning

publish_study spends real money. Once a study is published on Prolific, participants can start it immediately and you are charged for their work. Treat any LLM-driven invocation as a real spend: review the study draft and reward before approving the tool call. There is no sandbox mode — the same endpoint is used in production.

What it does

Exposes a small set of tools so an LLM can help a researcher design and launch a study on Prolific:

Tool	Prolific endpoint
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	(no Prolific endpoint — returns a deterministic app preview 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/ (existence only — see note below)
create_webhook_secret	POST /api/v1/hooks/secrets/
create_webhook_subscription	POST /api/v1/hooks/subscriptions/ + confirm
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	(local — no Prolific endpoint; reports server version, target API URL, and registered tools)

Note

Webhook secrets are handled deliberately narrowly. create_webhook_secret is the only tool in this repo that returns sensitive material, and only once, on first creation for a workspace — there's no tool to list or re-fetch an existing secret's value, since that value would then sit in the LLM's context on every read. If a workspace already has a secret and you need to see its value again (e.g. to reconfigure a receiver), that's prolific hook secrets -w <workspace_id> via the CLI, not MCP.

Requirements

• Python 3.11+
• A Prolific API token (create one at https://app.prolific.com)

Quickstart

Install and run from PyPI with uv:

export PROLIFIC_TOKEN=your_token_here
uvx prolific-mcp

Or from a checkout:

uv sync
export PROLIFIC_TOKEN=your_token_here
uv run prolific-mcp

The server defaults to stdio and is intended to be launched by an MCP client (Claude Desktop, Cursor, etc.).

Local development (HTTP mode)

Stdio gives the client ownership of the process, which hides server logs. For local iteration, run over streamable HTTP instead so logs stream to your terminal:

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

Override host/port with --host / --port if 8765 is in use.

Environment variables

Variable	Required	Default	Description
PROLIFIC_TOKEN	yes	—	Prolific API token, sent as Authorization: Token …
PROLIFIC_URL	no	https://api.prolific.com	Base URL of the Prolific API
PROLIFIC_APPLICATION_URL	no	https://app.prolific.com	Base URL of the Prolific web app, used for preview_collection's link

Use with MCP clients

Claude Desktop

Each GitHub Release attaches a .mcpb bundle per platform (darwin-arm64, darwin-x86_64, linux-x86_64, windows-x86_64). Download the file for your platform and open it — Claude Desktop will show an install dialog and prompt for your PROLIFIC_TOKEN.

To configure manually instead, add the server to your Claude Desktop config:

{
  "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

To pin a specific version, replace uvx prolific-mcp with uvx prolific-mcp==<version>.

Codex CLI

Add to ~/.codex/config.toml:

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

Restart Codex (or start a new session) to pick it up.

Cursor and other MCP-aware clients

Most clients accept the same command / args / env shape shown in the Claude Desktop JSON above.

Development

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