@askaudience/mcp-server

Model Context Protocol (MCP) server that exposes AskAudience as tools for AI assistants — Claude Desktop, Cursor, and any other MCP-compatible client.

AskAudience provides synthetic Digital Humans based on real European survey respondents (ESS R11 + WVS W7). Run market research in seconds — with Ø 94% accuracy from real survey responses (verified against ESS R11, n=165, 6 dimensions).

🎯 Kostenlos testen

25 Credits gratis — keine Kreditkarte nötig. Registriere dich mit deiner geschäftlichen E-Mail-Adresse und teste den Node sofort.

👉 Jetzt kostenlos starten

Prerequisites

• Node.js ≥ 18
• An AskAudience API key — get one at askaudience.de/console

Quick Start (Claude Desktop)

Add the following to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "askaudience": {
      "command": "npx",
      "args": ["-y", "@askaudience/mcp-server"],
      "env": {
        "ASKAUDIENCE_API_KEY": "aa_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You will see the AskAudience tools available in the tool panel.

Running Manually

# stdio (default — for Claude Desktop / Cursor)
ASKAUDIENCE_API_KEY=aa_... npx @askaudience/mcp-server

# SSE transport (HTTP server — for web clients)
ASKAUDIENCE_API_KEY=aa_... TRANSPORT=sse PORT=3000 npx @askaudience/mcp-server

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | ASKAUDIENCE_API_KEY | Yes | — | Your API key (aa_...) | | ASKAUDIENCE_BASE_URL | No | https://askaudience.de/api/v1 | Override the API base URL | | TRANSPORT | No | stdio | stdio or sse | | PORT | No | 3000 | HTTP port (SSE transport only) |

Available Tools

Audience Tools

askaudience_create_audience

Create a new synthetic target audience with demographic filters.

Parameters:
  name          string   Required. Audience display name
  description   string   Optional description
  sampleSize    number   Number of digital humans (default: 50)
  filters       object   Demographic filters:
    ageRange      { min, max }
    gender        "male" | "female" | "diverse"
    locations     string[]    e.g. ["Berlin", "München"]
    jobTitles     string[]
    jobSearch     string      Free-text job filter
    archetype     string      e.g. "career_driven"
    countryCode   "DE" | "AT" | "CH"
    sourceDataset "ess" | "wvs"

askaudience_ask_audience

Ask a question to an audience. Returns individual answers + aggregated distribution. Cost: 5 credits × sample size

Parameters:
  audienceId      string   Required
  question        string   Required
  sampleSize      number   default: 20
  responseFormat  "text" | "likert_5" | "likert_7" | "yes_no" | "rating_1_10"

askaudience_compare_audiences

Ask the same question to multiple audiences and compare responses side-by-side. Cost: 5 credits × sample size × number of audiences

Parameters:
  audienceIds     string[]  Required (min 2)
  question        string    Required
  sampleSize      number    per audience, default: 10
  responseFormat  string

askaudience_export_audience

Export audience demographic data as JSON or CSV. Cost: 1 credit

Parameters:
  audienceId  string   Required
  format      "json" | "csv"   default: json

Twin Tools

askaudience_search_digital_humans

Search for individual synthetic personas by free-text and filters. Cost: 2 credits

Parameters:
  query    string   Required. Searches name, location, job, description
  filters  object   { gender, ageMin, ageMax, location, interests[] }
  limit    number   default: 20

askaudience_ask_digital_human

Ask a single persona a question with grounded response. Cost: 5 credits

Parameters:
  twinId           string   Required
  question         string   Required
  responseFormat   string   default: text
  context          string   Optional background info
  includeReasoning boolean  default: false

Usage Tools

askaudience_get_usage

Check credit balance, plan, and request statistics. Free

Parameters:
  period  "day" | "week" | "month"   default: month

Survey Tools

askaudience_create_survey

Run a multi-question survey against an audience (async). Cost: 5 × twins × questions

Parameters:
  audienceId      string   Required
  title           string   Required
  description     string
  twinSampleSize  number   default: 50
  questions       Array<{
    id:       string
    type:     "open_text" | "likert_5" | "likert_7" | "multiple_choice"
              | "single_choice" | "rating_1_10" | "yes_no"
    text:     string
    options?: string[]   (required for choice types)
    required: boolean
  }>

askaudience_get_survey_status

Poll survey status (DRAFT → RUNNING → COMPLETED | FAILED). Cost: 1 credit

Parameters:
  surveyId  string   Required

askaudience_export_survey

Export completed survey results. Cost: 1–2 credits

Parameters:
  surveyId  string   Required
  format    "json" | "csv"   default: json

Example Prompts for Claude

Once configured, you can ask Claude:

"Create a target audience of women aged 30-45 in Berlin working in marketing, then ask them how important sustainability is when making purchase decisions."

"Search for software engineers in München and ask the top result what they think about working remotely."

"Compare how our 'Young Urban' and 'Traditional Rural' audiences respond to the question: Is AI a threat or an opportunity?"

"Check my AskAudience credit usage for this month."

SSE Transport (HTTP Mode)

For web-based MCP clients or custom integrations:

ASKAUDIENCE_API_KEY=aa_... TRANSPORT=sse PORT=3000 npx @askaudience/mcp-server

Endpoints:

• GET /sse — Establish SSE connection
• POST /message?sessionId=<id> — Send messages
• GET /health — Health check

Credits

| Operation | Credits | |-----------|---------| | Create audience | 3 | | Ask audience (per twin) | 5 | | Compare audiences (per twin per audience) | 5 | | Export audience | 1 | | Search twins | 2 | | Ask twin | 5 | | Create + run survey (per twin × question) | 5 | | Get survey status | 1 | | Export survey results | 1–2 | | Get usage | 0 |

License

MIT

Built for AskAudience — Grounded synthetic audiences for European market research.