Prolific Mcp Server

prolific-mcp

一个 Model Context Protocol 服务，可将大模型 Agent 接入 Prolific 公共 API。基于 FastMCP 构建。

已列入 官方 MCP 注册表，可通过 Claude Desktop、Cursor、Claude Code 及其他支持 MCP 的客户端发现。

警告

**publish_study 会产生实际费用。**在 Prolific 上发布研究后，参与者可以立即开始，您需要为他们的工作付费。请将任何由大模型驱动的调用都视为实际支出：在批准工具调用前，先检查研究草稿和报酬。此服务没有沙盒模式——使用的始终是生产环境中的同一端点。

功能

提供一组精简的工具，帮助大模型协助研究人员在 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 是本仓库中唯一会返回敏感信息的工具，而且仅在首次为工作区创建密钥时返回一次——没有工具可以列出或重新获取已有密钥的值，因为这样一来，每次读取时，该值都会留在大模型的上下文中。如果工作区已有密钥，而你需要再次查看其值（例如，重新配置接收端），请通过 CLI 执行 prolific hook secrets -w <workspace_id>，而不是使用 MCP。

要求

• 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 Release 都会附带适用于各平台的 .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