crowdos-mcp 0.1.0

Model Context Protocol server for CrowdOS — synthetic focus groups as agent-callable tools.

CrowdOS MCP Server

Synthetic focus groups as agent-callable tools. Exposes the CrowdOS developer API as Model Context Protocol tools so AI agents (Claude Desktop, Cursor, Cline, LangGraph, CrewAI, AutoGPT, Devin, etc.) can run synthetic public-opinion research with a single tool call.

What this gives you

Your agent can now do things like:

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

[tool: run_focus_group]
{
  "id": "ad4b3736-...",
  "sentiment_summary": {
    "support_pct": 71.5, "oppose_pct": 18.0, "mixed_pct": 10.5
  },
  "sample_responses": [
    {"agent_name": "Maria Chen", "stance": "supports", ... },
    ...
  ]
}

Installation

pip install crowdos-mcp

Then mint a free sandbox API key at https://crowdos.ai/developers — no credit card required for the free tier (50 agents per study, 5 req/min).

Configure for 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 should appear in the slash-command picker.

Configure for Cursor

Settings → MCP Servers → Add. Same env block as above; command = crowdos-mcp.

Configure for Cline (VS Code)

Settings → Cline → MCP Servers → Edit JSON:

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

Tools exposed

Tool	What it does	Auth
run_focus_group	Synthetic poll on a topic, returns sentiment + quotes	required
run_debate	Multi-round synthetic debate, returns convergence	required
list_demographic_presets	Discover available audience templates	required
get_simulation	Fetch full results of a previously-run study	required
crowd_sample	Browse the public CrowdOS crowd (sanitized)	none

run_focus_group and run_debate block 5–120s depending on population size — that's a real synthetic-research call running behind the scenes, not a cached response. The MCP server returns a trimmed envelope (sentiment summary + first 5 representative quotes

• billing breakdown). Use get_simulation to pull the full payload when you need every agent's full reasoning.

Configuration

Env var	Default	Required
CROWDOS_API_KEY	—	yes (except crowd_sample)
CROWDOS_API_BASE_URL	https://api.crowdos.ai	no

Cost

CrowdOS uses a metered wallet. The MCP server returns the actual debit on every successful call inside billing.actual_cents. Free tier ships with $5 of credit; top up at https://crowdos.ai/account/billing once it runs out.

Free-tier monthly quota is 120k tokens (~3 large studies). Pro tier removes the cap.

Programmatic use (without an MCP host)

The server is also a regular Python module:

python -m crowdos_mcp
# stdio MCP server, waits for messages on stdin

Or import and embed:

from crowdos_mcp.server import build_server
server = build_server()
# server is a configured mcp.server.Server instance

Versioning

Follows semver. The MCP tool surface (tool names, input schemas) is stable; additive changes (new tools, new optional fields) ship as minor versions. Removing or renaming a tool is a major version.

License

MIT.

Issues / questions

https://github.com/bjnagent/crowd/issues