内容
# prolific-mcp
[](https://github.com/prolific-oss/prolific-mcp/actions/workflows/ci.yml)
[](https://snyk.io/test/github/prolific-oss/prolific-mcp)
一款<Model Context Protocol>服务器，用于连接LLM代理到[Prolific]公共API。 使用[FastMCP]构建。
列入[官方MCP注册表](https://registry.modelcontextprotocol.io/v0/servers?search=prolific) — 可从Claude Desktop，Cursor，Claude Code等MCP客户端发现。
> [!WARNING]
> **`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/` |
## 要求
- Python 3.11+
- Prolific API令牌（在 <https://app.prolific.com> 创建一个）
## 快速入门
使用[`uv`](https://docs.astral.sh/uv/)从PyPI安装和运行：
```bash
export PROLIFIC_TOKEN=你的令牌
uvx prolific-mcp
```
或从checkout：
```bash
uv sync
export PROLIFIC_TOKEN=你的令牌
uv run prolific-mcp
```
服务器默认为stdio，旨在由MCP客户端（Claude Desktop，Cursor等）启动。
### 本地开发（HTTP模式）
stdio使客户端拥有进程，这会隐藏服务器日志。 对于本地迭代，请改为流式HTTP运行，以便日志流式传输到您的终端：
```bash
PROLIFIC_TOKEN=你的令牌 uv run prolific-mcp --http
# 服务器监听 http://127.0.0.1:8765/mcp
# 在另一个终端中将其注册到Claude Code：
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 |
## 与MCP客户端一起使用
### Claude Desktop
每个[GitHub Release](https://github.com/prolific-oss/prolific-mcp/releases)都附带一个`.mcpb`包（每个平台一个）。 下载适用于您平台的文件并打开它 — Claude Desktop将显示安装对话框并提示您输入 `PROLIFIC_TOKEN`。
要手动配置，请将服务器添加到Claude Desktop配置中：
```json
{
"mcpServers": {
"prolific": {
"command": "uvx",
"args": ["prolific-mcp"],
"env": { "PROLIFIC_TOKEN": "你的令牌" }
}
}
}
```
### Claude Code
```bash
claude mcp add prolific \
-e PROLIFIC_TOKEN=你的令牌 \
-- uvx prolific-mcp
```
要固定特定版本，请将 `uvx prolific-mcp` 替换为 `uvx prolific-mcp==<版本>`。
### Codex CLI
将以下内容添加到 `~/.codex/config.toml`:
```toml
[mcp_servers.prolific]
command = "uvx"
args = ["prolific-mcp"]
env = { PROLIFIC_TOKEN = "你的令牌" }
```
重启Codex（或启动新会话）以使其生效。
### Cursor 和其他MCP感知客户端
大多数客户端接受与上述Claude Desktop JSON中所示的相同的 `command` / `args` / `env` 格式。
## 开发
```bash
uv sync
uv run pytest # 测试
uv run mypy # 类型检查
uv run ruff check . # 校验
uv run ruff format . # 格式化
```
## Docker
```bash
docker build -t mcp/prolific .
docker run -i --rm -e PROLIFIC_TOKEN=$PROLIFIC_TOKEN mcp/prolific
```
