OpenQual

Open-source Qualtrics research assistant with local estimation and Telegram integration.

OpenQual connects Claude to your Qualtrics account through a typed MCP server, runs all statistical analysis locally (no human-subjects data leaves your machine), and lets you interact via web chat, voice, or Telegram.

Three Pillars

Qualtrics MCP Server

A TypeScript Model Context Protocol server that gives Claude typed tool access to the Qualtrics API:

• List & search surveys — fuzzy matching with synonym expansion (e.g. "NPS" matches "net promoter")
• Export responses — paginated CSV export with automatic data profiling
• Filter & inspect — column-level metadata, response counts, question mappings
• Create surveys — programmatic survey creation via the API

The MCP server runs as a subprocess alongside the main app. See qualtrics-mcp-server/ for source.

Local Estimation

All statistics run in isolated Python subprocesses on your machine. Survey data is never sent to external APIs — only summaries and interpretations are returned to Claude.

Built-in analysis capabilities:

Agent	What it does
ATE	Average treatment effects with robust standard errors
Regression	OLS/logit with heteroskedasticity-robust SEs
Heterogeneity	Subgroup treatment effect variation
Descriptive stats	Summary statistics, distributions, missing data
Quality checks	Data quality assessment, outlier detection
Report	Natural language summaries of statistical findings

Stack: pandas, statsmodels, scipy, Plotly (with Kaleido for PNG export).

Telegram Integration

Run OpenQual as a Telegram bot for mobile-friendly access:

• Voice messages transcribed and analyzed
• Plotly charts rendered as PNG and sent inline
• Per-chat session isolation
• Access control via allowed chat IDs

Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+ (for MCP server)
• Redis (for session management)
• API keys: Anthropic, Qualtrics, optionally OpenAI (TTS) and Telegram

Local Setup

git clone https://github.com/yrvelez/OpenQual.git
cd OpenQual

# Python dependencies
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# MCP server
cd qualtrics-mcp-server
npm install
npm run build
cd ..

# Configuration
cp .env.example .env
# Edit .env with your API keys

# Run
uvicorn src.api.main:app --host 0.0.0.0 --port 8000

Docker

cp .env.example .env
# Edit .env with your API keys

docker compose up -d

This starts the app on port 8000 with Redis for session management.

Configuration

All configuration is via environment variables (see .env.example):

Variable	Required	Description
ANTHROPIC_API_KEY	Yes	Claude API key
QUALTRICS_API_TOKEN	Yes	Qualtrics API token
QUALTRICS_DATA_CENTER	Yes	Qualtrics data center ID
REDIS_URL	Yes	Redis connection URL
TELEGRAM_BOT_TOKEN	No	Telegram bot token
TELEGRAM_WEBHOOK_URL	No	Public URL for Telegram webhook
OPENAI_API_KEY	No	OpenAI key for TTS
TWILIO_ACCOUNT_SID	No	Twilio SID for voice/SMS
TWILIO_AUTH_TOKEN	No	Twilio auth token
TWILIO_PHONE_NUMBER	No	Twilio phone number
ALLOWED_PHONE_NUMBERS	No	Comma-separated allowlist
PYTHON_EXECUTOR_TIMEOUT	No	Script timeout in seconds (default: 60)
MAX_EXPORT_ROWS	No	Max rows per export (default: 10000)

Project Structure

OpenQual/
├── src/
│   ├── agents/
│   │   ├── orchestrator.py          # Claude orchestrator (routes tools, streams responses)
│   │   └── tools/
│   │       └── qualtrics_tools.py   # Python-side Qualtrics tool definitions
│   ├── api/
│   │   ├── main.py                  # FastAPI app
│   │   ├── config.py                # Settings (pydantic-settings)
│   │   ├── models/
│   │   │   └── session.py           # Session & analysis state models
│   │   └── routers/
│   │       ├── chat.py              # WebSocket chat endpoint
│   │       ├── telegram.py          # Telegram webhook handler
│   │       ├── webhook.py           # GitHub auto-deploy webhook
│   │       ├── health.py            # Health check
│   │       └── debug.py             # Debug endpoints
│   └── services/
│       ├── python_executor.py       # Sandboxed Python subprocess runner
│       ├── session_manager.py       # Redis-backed session management
│       └── telegram_session_manager.py
├── qualtrics-mcp-server/            # TypeScript MCP server
│   ├── src/
│   │   ├── server.ts                # MCP server entry point
│   │   ├── tools/index.ts           # Tool definitions (list, export, create)
│   │   ├── services/
│   │   │   ├── qualtrics-client.ts  # Qualtrics API client
│   │   │   └── rate-limiter.ts      # Request rate limiting
│   │   └── config/settings.ts       # MCP server config
│   ├── package.json
│   └── tsconfig.json
├── static/
│   └── chat.html                    # Web chat UI
├── tests/
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
└── .env.example

License

MIT