qualtrics-mcp

EderBuug/qualtrics-mcp

3.2

If you are the rightful owner of qualtrics-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server for integrating with the Qualtrics API, enabling AI models like Claude to interact with Qualtrics surveys, libraries, messages, and SMS distributions.

Tools
6
Resources
0
Prompts
0

Qualtrics MCP Server

Python Version License: MIT Code style: ruff

Un servidor Model Context Protocol (MCP) para integración con la API de Qualtrics, permitiendo a los modelos de IA como Claude interactuar con encuestas, librerías, mensajes y distribuciones SMS de Qualtrics.

🌟 Características

  • 6 Herramientas MCP listas para usar con funcionalidades esenciales de Qualtrics
  • Cliente HTTP asíncrono con httpx para llamadas eficientes
  • Paginación automática de respuestas de la API
  • Manejo robusto de errores con validación completa
  • Configuración flexible vía variables de entorno o configuración dinámica
  • Type hints completos para mejor mantenibilidad
  • Arquitectura modular fácil de extender

🚀 Instalación

Opción 1: Desde PyPI (Recomendado - Próximamente)

# Con pip
pip install qualtrics-mcp

# Con uv (recomendado)
uv add qualtrics-mcp

Opción 2: Desde el código fuente

# Clonar el repositorio
git clone https://github.com/EderBuug/qualtrics-mcp.git
cd qualtrics-mcp

# Instalar dependencias
uv sync

# O con pip
pip install -e .

⚙️ Configuración

1. Obtener credenciales de Qualtrics

  1. Inicia sesión en tu cuenta de Qualtrics
  2. Ve a Account Settings → Qualtrics IDs
  3. Genera un API Token
  4. Identifica tu Data Center (ej: ca1, sjc1, fra1)

2. Configurar variables de entorno

Crea un archivo .env en la raíz del proyecto:

cp env.example .env

Edita el archivo .env con tus credenciales:

QUALTRICS_API_TOKEN=tu_token_aqui
QUALTRICS_DATA_CENTER=ca1
QUALTRICS_BASE_URL=https://ca1.qualtrics.com

📖 Uso

Ejecutar el servidor MCP

# Directamente
python main.py

# O con uv
uv run python main.py

Configurar en Claude Desktop

Edita el archivo de configuración de Claude Desktop:

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

Agrega la siguiente configuración:

{
  "mcpServers": {
    "qualtrics": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/ruta/a/tu/qualtrics-mcp",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "QUALTRICS_API_TOKEN": "tu_token_aqui",
        "QUALTRICS_DATA_CENTER": "ca1"
      }
    }
  }
}

Ver para más opciones.

🛠️ Herramientas MCP Disponibles

El servidor expone 6 herramientas que pueden ser utilizadas por cualquier cliente MCP:

1. configurar_credenciales

Configura las credenciales de API de Qualtrics dinámicamente.

Parámetros:

  • api_token (string): Token de API de Qualtrics
  • data_center (string): Centro de datos (ej: 'ca1', 'sjc1')

2. obtener_librerias

Lista todas las librerías disponibles en tu cuenta de Qualtrics.

Retorna: Lista de librerías con ID, nombre, tipo y fechas.

3. obtener_mensajes_libreria

Obtiene todos los mensajes de una librería específica.

Parámetros:

  • library_id (string): ID de la librería (ej: "UR_123abc")

4. obtener_detalle_mensaje

Obtiene información detallada de un mensaje específico.

Parámetros:

  • library_id (string): ID de la librería
  • message_id (string): ID del mensaje (ej: "MS_123abc")

5. obtener_encuestas

Lista todas las encuestas con estadísticas completas.

Retorna: Lista de encuestas con estadísticas de activas/inactivas, propietarios, etc.

6. obtener_distribuciones_sms

Lista las distribuciones SMS de una encuesta.

Parámetros:

  • survey_id (string): ID de la encuesta (formato: SV_[a-zA-Z0-9]{11,15})

Retorna: Distribuciones con estadísticas de envío, fallos, créditos usados, etc.

🏗️ Estructura del Proyecto

qualtrics-mcp/
├── src/qualtrics_mcp/          # Código fuente principal
│   ├── server.py               # Servidor MCP con FastMCP
│   ├── config.py               # Gestión de configuración
│   ├── api/
│   │   └── client.py           # Cliente HTTP para Qualtrics API
│   └── tools/                  # Implementación de herramientas MCP
│       ├── libraries.py        # Librerías y mensajes
│       ├── surveys.py          # Gestión de encuestas
│       └── distributions.py    # Distribuciones SMS
├── tests/                      # Tests unitarios
├── docs/                       # Documentación detallada
├── examples/                   # Ejemplos de configuración
├── LICENSE                     # Licencia MIT
├── README.md                   # Este archivo
└── pyproject.toml              # Configuración del proyecto

🧪 Desarrollo

Instalar dependencias de desarrollo

uv sync --dev

Ejecutar tests

uv run pytest

# Con cobertura
uv run pytest --cov=src/qualtrics_mcp

Linting y formateo

# Verificar estilo
uv run ruff check src/ tests/

# Formatear código
uv run ruff format src/ tests/

# Type checking
uv run mypy src/

Probar con MCP Inspector

# Instalar MCP Inspector (requiere Node.js)
npm install -g @modelcontextprotocol/inspector

# Ejecutar con Inspector
npx @modelcontextprotocol/inspector uv --directory . run python main.py

Ver .

📚 Documentación

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor:

  1. Fork el proyecto
  2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
  3. Commit tus cambios (git commit -m 'Add AmazingFeature')
  4. Push a la rama (git push origin feature/AmazingFeature)
  5. Abre un Pull Request

Ver para más detalles.

📝 Changelog

Ver para historial de cambios.

📄 Licencia

Este proyecto está bajo la licencia MIT. Ver el archivo para más detalles.

🔗 Enlaces

💬 Soporte

Hecho con ❤️ para la comunidad de MCP y Qualtrics