Qualtrics MCP

Qualtrics MCP Server

](https://www.python.org/downloads/)  

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 documentación detallada 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 guía completa del Inspector.

📚 Documentación

• Instalación Completa
• Configuración de Claude Desktop
• Prueba Rápida
• Usar con MCP Inspector

🤝 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 CONTRIBUTING.md para más detalles.

📝 Changelog

Ver CHANGELOG.md para historial de cambios.

📄 Licencia

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

🔗 Enlaces

• Documentación de Qualtrics API
• Model Context Protocol
• FastMCP

💬 Soporte

• 🐛 Reportar bugs
• 💡 Solicitar features
• 📖 Documentación

Hecho con ❤️ para la comunidad de MCP y Qualtrics