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/ |
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 |
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
Server Config
{
"mcpServers": {
"prolific": {
"command": "uvx",
"args": [
"prolific-mcp"
],
"env": {
"PROLIFIC_TOKEN": "your_token_here"
}
}
}
}