simulatte

Simulatte MCP Server

通过 Claude、Cursor、Zed 或任何兼容 MCP 的 AI 客户端运行 Simulatte 的 26 种 SKU。以结构化 JSON 获取结果。无需学习新的界面。

User: "Test this sleep coaching concept on 50 stressed parents."
Claude: [calls simulatte_estimate_cost] → 150 credits (~$1.80). Approve?
User: "yes"
Claude: [calls simulatte_run_study] → Results in 4 minutes.

---

安装

临时运行（无需安装）：

SIMULATTE_API_KEY=sim_live_your_key npx @simulatte-io/mcp-server

全局安装：

npm install -g @simulatte-io/mcp-server
SIMULATTE_API_KEY=sim_live_your_key simulatte-mcp

---

获取 API 密钥

1. 前往 app.simulatte.io/settings/api-keys
2. 创建密钥——以 sim_live_ 开头
3. 在环境变量或 MCP 客户端配置中将其设为 SIMULATTE_API_KEY

---

配置 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "simulatte": {
      "command": "npx",
      "args": ["-y", "@simulatte-io/mcp-server"],
      "env": {
        "SIMULATTE_API_KEY": "sim_live_your_key_here"
      }
    }
  }
}

重启 Claude Desktop。Simulatte 工具会自动显示。

---

配置 Cursor

编辑 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "simulatte": {
      "command": "npx",
      "args": ["-y", "@simulatte-io/mcp-server"],
      "env": {
        "SIMULATTE_API_KEY": "sim_live_your_key_here"
      }
    }
  }
}

---

配置 Zed

在 ~/.config/zed/settings.json 中添加：

{
  "context_servers": {
    "simulatte": {
      "command": {
        "path": "npx",
        "args": ["-y", "@simulatte-io/mcp-server"],
        "env": {
          "SIMULATTE_API_KEY": "sim_live_your_key_here"
        }
      }
    }
  }
}

---

可用工具

工具	功能
simulatte_run_study	运行 26 种研究 SKU 中的任意一种——概念测试、定价、信息传达、B2B 委员会等
simulatte_get_results	获取已完成研究的完整结构化结果
simulatte_ask_insights	针对全部研究历史提出自然语言问题
simulatte_list_pools	列出工作区中的所有合成角色池
simulatte_create_pool	根据自定义人口统计／心理特征规格创建角色池
simulatte_depth_interview	与合成角色进行多轮模拟深度访谈
simulatte_estimate_cost	在运行研究前估算点数和美元费用（本地计算——不调用 API）

simulatte_run_study 支持的 SKU

概念可行性 · 声明可信度 · 品牌身份测试 · 信息共鸣度 · 价格敏感度 · 功能优先级 · 广告文案 · B2B 委员会 · 联合分析 · iris-pulse · 卡片分类 · 开放式问题 · ab-backlog · 两极化压力测试 · 名称测试 · 创始人定位 · 广告概念共鸣度 · 深度访谈 · 自定义研究 · iat · 反事实定位 · 个性化敏感度 · 受监管声明预检 · 量级预测 · 品牌追踪 · 创意审核

---

示例提示词

概念测试：

“我有一个新的睡眠辅导应用概念。用 50 位压力大的家长角色进行测试，并告诉我这个概念是否会受欢迎。”

定价敏感度：

“针对 100 位千禧一代专业人士，对我的高级方案（99 美元／月）开展价格敏感度研究。使用 pool_abc123。”

跨研究综合分析：

“本季度所有 B2B 研究中最常见的反对意见是什么？”

深度访谈：

“围绕我们的引导流程，采访一位持怀疑态度的 35 岁英国家长，进行 15 轮。”

---

身份验证

首选：每位客户使用独立 API 密钥

在以下任一请求头中发送你的 sim_live_* 密钥——两种方式都受支持：

x-api-key: sim_live_your_key_here
# or
Authorization: Bearer sim_live_your_key_here

已弃用：共享平台密钥

共享密钥 forge-prod-2026（在 v0.4 之前用于内部集成）已弃用，并且将在 v0.5 移除。如果你的集成发送 x-api-key: forge-prod-2026，请立即迁移到每位客户独立的 sim_live_* 密钥。 每当请求使用共享密钥时，worker 都会记录弃用警告。

---

响应头

每个成功的 /v1/forge/* 和 /v1/iris/* 响应都会包含以下请求头：

请求头	说明
X-Simulatte-Credits-Used	此请求扣除的点数
X-Simulatte-Credits-Remaining	扣除后工作区的点数余额
X-Simulatte-Spend-Warning	仅当你的密钥已消耗 ≥ 80% 的消费上限时出现。值为："85%-of-cap-consumed"（百分比可能有所不同）。

显示所有请求头的 curl 示例

curl -X POST https://forge-worker-production.up.railway.app/v1/forge/concept-viability \
  -H "x-api-key: sim_live_your_key" \
  -H "x-workspace-id: your-workspace-uuid" \
  -H "Content-Type: application/json" \
  -d '{"concept":"A sleep app for stressed parents","population_id":"default","sample_size":20}' \
  -i

预期响应头（2xx）：

HTTP/2 201
x-simulatte-credits-used: 28
x-simulatte-credits-remaining: 472

如果你的密钥已达到消费上限的 85%：

x-simulatte-spend-warning: 85%-of-cap-consumed

---

错误参考

状态	error 字段	含义
401	invalid_api_key	未找到密钥、密钥已撤销或已过期
401	（消息）	Bearer JWT 无效或已过期
402	key_spend_cap_exceeded	密钥设有支出上限，此请求将超出上限。正文：{"error":"key_spend_cap_exceeded","cap":500,"used":498,"would_charge":10}
429	rate_limited	已达到每分钟 60 次或每小时 1,000 次的限制。请检查 Retry-After 标头
503	database_unavailable	无法连接 Worker DB——请在 30 秒后重试

错误正文示例

402 — 超出支出上限：

{
  "detail": {
    "error": "key_spend_cap_exceeded",
    "cap": 500,
    "used": 498,
    "would_charge": 10
  }
}

429 — 请求过于频繁：

{
  "detail": {
    "error": "rate_limited",
    "limit": "60/min",
    "retry_after_seconds": 42
  }
}

同时还会包含 Retry-After: 42 标头。

---

速率限制与配额

每个 API 密钥都会单独执行速率限制和额度上限：

默认限制	数值
每分钟	60 次/分钟
每小时	1,000 次/小时

支出上限为可选项，由工作区管理员按密钥设置。未设支出上限的密钥可无限支出（但受工作区额度余额限制）。

请访问 app.simulatte.io/settings/billing 查看当前用量。

---

故障排除

“缺少 SIMULATTE_API_KEY” — 请确保 MCP 配置中的 env 块包含你的密钥。密钥必须以 sim_live_ 开头。

Claude Desktop 中未显示工具 — 编辑 claude_desktop_config.json 后，请重启 Claude Desktop。请检查 MCP 日志：~/Library/Logs/Claude/mcp*.log。

simulatte_get_results 返回 status: "running" — 研究需要 2–8 分钟。请在 30 秒后再次轮询，或让 Claude 等待后重试。

401 未授权 — 你的 API 密钥可能已撤销或不正确。请在 app.simulatte.io/settings/api-keys 生成新密钥。

429 请求过多 — 你已达到当前套餐的速率限制。请在 app.simulatte.io/settings/billing 升级。

---

开发

git clone https://github.com/Iqbalahmed7/simulatte-mcp-server
cd simulatte-mcp-server
npm install
npm run build    # compiles TypeScript → dist/
npm test         # runs vitest test suite
npm run dev      # runs directly via tsx (no build step)

---

许可证

MIT — 详见 LICENSE。