CrowdOS MCP Server

Simulated focus groups as agent-callable tools. Connects AI agents (Claude Desktop, Cursor, Cline, LangGraph, CrewAI, and any other Model Context Protocol host) to CrowdOS, so they can run simulated public-opinion research with a single tool call.

Every plan can use it — Free, Pro and Max — at that plan's limits on the web. Enterprise accounts get every tool.

What this gives you

> Run a focus group on whether companies should mandate 4-day weeks.
   Use 200 people from the us_general_population preset.

[tool: run_focus_group]
{
  "id": "ad4b3736-...",
  "sentiment_summary": {
    "positive_pct": 71.5, "negative_pct": 18.0, "neutral_pct": 10.5,
    "positive": 143, "negative": 36, "neutral": 21
  },
  "total_responses": 200,
  "billing": { "actual_cents": 400 }
}

Two ways to connect

Hosted (no install). Add https://api.crowdos.ai/mcp as a remote MCP server in any client that supports them (claude.ai connectors, Cursor, agent frameworks). OAuth-capable clients sign in and approve on first connect; the grant shows up as a revocable key under Account → MCP keys. Header-based clients pass Authorization: Bearer crowd_....

This package (stdio, for desktop hosts). Since 1.0.0 the package is a thin relay to that same hosted endpoint: it holds no tools of its own, so the tools, limits and checks your agent sees are exactly the ones your key has there, and a new tool reaches you without an upgrade.

pip install crowdos-mcp

Then create an MCP key at https://crowdos.ai/account/api-keys (any plan can).

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "crowdos": {
      "command": "crowdos-mcp",
      "env": {
        "CROWDOS_API_KEY": "crowd_..."
      }
    }
  }
}

Restart Claude Desktop; the CrowdOS tools appear in the tool picker.

Cursor / Cline

Same shape in their MCP-server settings: command crowdos-mcp, env CROWDOS_API_KEY.

Tools, and who gets them

test_pricing and rank_items need Pro or Max because their smallest panels (50 and 100 respondents) are larger than Free's limit — the same rule as the web app.

Limits by plan

On Free, Pro and Max the tools also take the web's 17 answer languages, and image_url and the saved-panel arguments are Enterprise-only. The hosted endpoint checks every call before it runs (an off-plan call comes back as not_on_your_plan or over_plan_cap, naming the limit to retry with), and the API checks it again.

Studies draw down your CrowdOS wallet at the same per-respondent prices as the web app; every run returns billing.actual_cents. Top up at https://crowdos.ai/account/billing.

Recommended flow

1. list_demographic_presets — if the user didn't pick an audience, propose one.
2. estimate_reach (free) — when using custom_audience. A small audience is not a blocked one: the panel is still delivered at the size you ask for, with every respondent matching the filter. Pass several related interest tags (they are OR-matched) rather than one.
3. preview_cost — the cents and seconds before committing.
4. Confirm with the user, then run.

Run tools block 5-120 s depending on panel size, and stream progress: when your host sends a progressToken (the default), it shows "47/200 respondents" live. If a call fails after the study launched, the error carries sim_id and recoverable: true — call get_simulation in 30-60 s rather than re-running, which would launch and bill a second study.

Errors

Failures come back as a typed envelope (isError set on the MCP result). The error field is one of:

Configuration

Versioning

Semver. 1.0.0 made the package a relay, so the tool surface is now the hosted endpoint's and follows the API's own deploys; the package itself changes only when the relay does.

Releasing: tag a commit already on main — git tag mcp-v<version> && git push origin mcp-v<version> — and .github/workflows/publish-mcp.yml builds and publishes to PyPI over Trusted Publishing. The run stops before building if the tag, pyproject.toml and __init__.py disagree, if the tests fail, or if the built server does not start on the installed SDK.

Changelog

• 1.0.0 — the package relays to https://api.crowdos.ai/mcp instead of calling the REST API itself: tools, limits and checks come from the hosted endpoint for your key's account. Every plan can use it (the REST API is for Enterprise accounts since Oct 10, 2026). Progress notifications and the sim_id on a dropped stream are relayed. New CROWDOS_MCP_URL.
• 0.12.x — the last releases that called the REST API directly.

License

MIT.

Issues / questions

Email hello@motifmotion.sg. Setup guide: https://crowdos.ai/mcp.