JotForm

Un servidor MCP para interactuar con la API de Jotform y gestionar formularios y envíos en línea.

GitHub
1
Prueba este MCPPatrocinado

Documentación

MseeP.ai Security Assessment Badge Verified on MseeP

API de JotForm - Cliente Python y Servidor MCP

smithery badge

Este repositorio contiene el cliente Python para la API de JotForm y un servidor MCP (Model Context Protocol) construido usando este cliente. El servidor MCP permite la interacción con la API de Jotform a través de herramientas estandarizadas.

Instalación mediante Smithery (Recomendado para clientes MCP)

Este servidor está disponible en Smithery. Puedes instalarlo y configurarlo fácilmente dentro de clientes MCP compatibles (como Windsurf):

  1. Buscar: En la interfaz de gestión de servidores de tu cliente MCP, busca servidores.
  2. Encontrar: Busca JotForm API Server o usa el ID @The-AI-Workshops/jotform-mcp-server.
  3. Instalar: Selecciona el servidor y haz clic en "Instalar".
  4. Configurar: Después de la instalación, se te pedirá configurar las variables de entorno requeridas. La más importante es:
    • JOTFORM_API_KEY: Tu clave de API de Jotform.

Smithery maneja la configuración subyacente (entorno Docker o Python) según la configuración del servidor.

Configuración para Claude Desktop y clientes MCP similares

Para Claude Desktop y otros clientes MCP que usan transporte stdio, puedes configurar el servidor de varias maneras:

Opción 1: CLI de Smithery (Windows/multiplataforma)

{
  "mcpServers": {
    "jotform-mcp-server": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@smithery/cli@latest",
        "run",
        "@The-AI-Workshops/jotform-mcp-server",
        "--key",
        "{\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"claude-ai\",\"version\":\"0.1.0\"}},\"jsonrpc\":\"2.0\",\"id\":0}",
        "--config",
        "\"{\\\"apiKey\\\":\\\"YOUR_JOTFORM_API_KEY\\\",\\\"baseUrl\\\":\\\"https://api.jotform.com/\\\",\\\"mcpHost\\\":\\\"0.0.0.0\\\",\\\"mcpPort\\\":\\\"8067\\\",\\\"debugMode\\\":\\\"False\\\",\\\"transport\\\":\\\"stdio\\\",\\\"outputType\\\":\\\"json\\\"}\""
      ]
    }
  }
}

Opción 2: Ejecución directa de Python

Linux/macOS:

{
  "mcpServers": {
    "jotform": {
      "command": "python",
      "args": ["/path/to/jotform-mcp-server/jotform_mcp_server.py"],
      "env": {
        "JOTFORM_API_KEY": "YOUR_JOTFORM_API_KEY"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "jotform": {
      "command": "python",
      "args": ["C:\\path\\to\\jotform-mcp-server\\jotform_mcp_server.py"],
      "env": {
        "JOTFORM_API_KEY": "YOUR_JOTFORM_API_KEY"
      }
    }
  }
}

Opción 3: Usando entorno virtual

Linux/macOS:

{
  "mcpServers": {
    "jotform": {
      "command": "/path/to/jotform-mcp-server/venv/bin/python",
      "args": ["/path/to/jotform-mcp-server/jotform_mcp_server.py"],
      "env": {
        "JOTFORM_API_KEY": "YOUR_JOTFORM_API_KEY"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "jotform": {
      "command": "C:\\path\\to\\jotform-mcp-server\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\jotform-mcp-server\\jotform_mcp_server.py"],
      "env": {
        "JOTFORM_API_KEY": "YOUR_JOTFORM_API_KEY"
      }
    }
  }
}

Opción 4: Usando uv (Recomendado para entornos Python)

{
  "mcpServers": {
    "jotform": {
      "command": "uv",
      "args": ["--directory", "/path/to/jotform-mcp-server", "run", "jotform_mcp_server.py"],
      "env": {
        "JOTFORM_API_KEY": "YOUR_JOTFORM_API_KEY"
      }
    }
  }
}

Autenticación

La API de JotForm requiere una clave de API para todas las llamadas relacionadas con el usuario. Puedes crear tus claves de API en la sección de API de la configuración de tu cuenta de JotForm. Esta clave es necesaria para ejecutar el servidor MCP, ya sea instalado manualmente o mediante Smithery.

Configuración manual y ejecución (para desarrollo o uso sin Smithery)

Instalación mediante Smithery

Para instalar el Servidor de API de JotForm para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @The-AI-Workshops/jotform-mcp-server --client claude

1. Clonar el repositorio:

git clone https://github.com/The-AI-Workshops/jotform-mcp-server.git
cd jotform-mcp-server

2. Crear entorno virtual (Recomendado):

python3 -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`

3. Instalar dependencias:

Elige uno de los siguientes métodos:

  • Usando uv (Recomendado):

    • Si no tienes uv, instálalo: pip install uv
    • Instala las dependencias usando el archivo de bloqueo para reproducibilidad: 
      uv pip sync uv.lock

  • Usando pip:

    • Instala las dependencias usando el archivo requirements.txt: 
      pip install -r requirements.txt

4. Configurar la clave de API:

  • Renombra el archivo .env.example a .env.
  • Abre el archivo .env y reemplaza "YOUR_JOTFORM_API_KEY_HERE" con tu clave de API real de Jotform.
  • También puedes ajustar otras configuraciones como MCP_PORT o JOTFORM_BASE_URL si es necesario.
# .env
JOTFORM_API_KEY="YOUR_ACTUAL_JOTFORM_API_KEY"
MCP_HOST="0.0.0.0"
MCP_PORT="8067"
MCP_TRANSPORT="sse"
JOTFORM_BASE_URL="https://api.jotform.com/"
JOTFORM_OUTPUT_TYPE="json"
JOTFORM_DEBUG_MODE="False"

# Custom Search Settings
ACCOUNTING_MONTH_START_DAY="1" # Day of the month the accounting period starts (e.g., 1, 15)

5. Ejecutar el servidor:

Asegúrate de que tu entorno virtual esté activado.

python jotform_mcp_server.py

El servidor se iniciará, normalmente escuchando en http://0.0.0.0:8067. Luego puedes conectarte a él usando un cliente MCP. Todos los métodos públicos de JotformAPIClient están expuestos como herramientas.

Ejecución con Docker

Se proporciona un Dockerfile para contenerizar el servidor MCP.

1. Construir la imagen de Docker:

Asegúrate de estar en el directorio raíz del proyecto (donde se encuentra el Dockerfile).

docker build -t jotform-mcp-server .

2. Ejecutar el contenedor de Docker:

Debes proporcionar tu clave de API de Jotform como variable de entorno al ejecutar el contenedor.

docker run -d -p 8067:8067 -e JOTFORM_API_KEY="YOUR_ACTUAL_JOTFORM_API_KEY" --name jotform-server jotform-mcp-server
  • -d: Ejecuta el contenedor en modo desacoplado (en segundo plano).
  • -p 8067:8067: Mapea el puerto 8067 de tu host al puerto 8067 del contenedor.
  • -e JOTFORM_API_KEY="...": Fundamentalmente, pasa tu clave de API aquí.
  • --name jotform-server: Asigna un nombre al contenedor para facilitar su gestión.
  • jotform-mcp-server: El nombre de la imagen que construiste.

El servidor MCP se ejecutará dentro del contenedor y será accesible en el puerto 8067 de tu máquina host.

Para ver los registros:

docker logs jotform-server

Para detener el contenedor:

docker stop jotform-server

Para eliminar el contenedor:

docker rm jotform-server

Integración con clientes MCP

Puedes conectarte a este servidor usando cualquier cliente compatible con MCP (como Windsurf, Claude Desktop, n8n, etc.). Aquí hay ejemplos de configuraciones para diferentes métodos de transporte:

Configuración SSE

Si ejecutas el servidor directamente (python jotform_mcp_server.py) o usando Docker con mapeo de puertos (como se muestra arriba), puedes conectarte vía SSE. Asegúrate de que TRANSPORT=sse esté configurado en tu archivo .env o se pase al contenedor de Docker.

Configuración estándar de MCP:

{
  "mcpServers": {
    "jotform": {
      "transport": "sse",
      "url": "http://localhost:8067/sse"
    }
  }
}

Configuración de Windsurf:

{
  "mcpServers": {
    "jotform": {
      "transport": "sse",
      "serverUrl": "http://localhost:8067/sse"
    }
  }
}

(Nota: Si te conectas desde otro contenedor Docker, como n8n, reemplaza localhost con host.docker.internal)

Configuración de Python con Stdio

Esto permite que el cliente MCP gestione el proceso del servidor directamente usando tu entorno Python local. Reemplaza your/path/to/ con la ruta absoluta real al directorio del proyecto.

{
  "mcpServers": {
    "jotform": {
      // Ensure this points to the python executable within the venv created by uv/pip
      "command": "your/path/to/jotform-mcp-server/venv/bin/python", // Use venv\Scripts\python.exe on Windows
      "args": ["your/path/to/jotform-mcp-server/jotform_mcp_server.py"],
      "env": {
        "TRANSPORT": "stdio",
        "JOTFORM_API_KEY": "YOUR_ACTUAL_JOTFORM_API_KEY",
        // Optional: Override other .env settings if needed
        "JOTFORM_BASE_URL": "https://api.jotform.com/",
        "JOTFORM_OUTPUT_TYPE": "json",
        "JOTFORM_DEBUG_MODE": "False"
      }
    }
  }
}

Configuración de Docker con Stdio

Esto permite que el cliente MCP gestione el proceso del servidor que se ejecuta dentro de un contenedor Docker. Asegúrate de haber construido la imagen (docker build -t jotform-mcp-server .).

{
  "mcpServers": {
    "jotform": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-e", "TRANSPORT=stdio",
               "-e", "JOTFORM_API_KEY", // Will be inherited from the 'env' section below
               "-e", "JOTFORM_BASE_URL",
               "-e", "JOTFORM_OUTPUT_TYPE",
               "-e", "JOTFORM_DEBUG_MODE",
               "jotform-mcp-server:latest" // Use the image tag you built
              ],
      "env": {
        "TRANSPORT": "stdio", // Required by the server script
        "JOTFORM_API_KEY": "YOUR_ACTUAL_JOTFORM_API_KEY",
        // Optional: Override other defaults if needed
        "JOTFORM_BASE_URL": "https://api.jotform.com/",
        "JOTFORM_OUTPUT_TYPE": "json",
        "JOTFORM_DEBUG_MODE": "False"
      }
    }
  }
}

Ejecución rápida (similar a npx)

Si quieres ejecutar el servidor rápidamente sin una configuración local completa (similar a cómo funciona npx para paquetes de Node.js), puedes combinar los pasos. Esto es útil para ejecución temporal o pruebas.

Asegúrate de tener Python 3.11+ y git instalados.

# 1. Clone the repository
git clone https://github.com/The-AI-Workshops/jotform-mcp-server.git
cd jotform-mcp-server

# 2. Create a temporary .env file with your API key
echo "JOTFORM_API_KEY=YOUR_ACTUAL_JOTFORM_API_KEY" > .env
# Optional: Add other ENV VARS like MCP_PORT=8067 if needed

# 3. Install dependencies and run (choose one method):

# Method A: Using pip (installs dependencies globally if not in a venv)
pip install -r requirements.txt && python jotform_mcp_server.py

# Method B: Using uv (installs uv then dependencies globally if not in a venv)
# pip install uv && uv pip sync uv.lock && python jotform_mcp_server.py

# 4. Stop the server with CTRL+C when done.
# 5. Remove the directory if you don't need it anymore: cd .. && rm -rf jotform-mcp-server

Nota: Este método podría instalar dependencias globalmente si no estás dentro de un entorno virtual activado. Se recomienda usar un entorno virtual dedicado (Pasos 2 y 3 en la configuración principal) o Docker para un mejor aislamiento del proyecto.

Herramientas disponibles

Este servidor expone las siguientes herramientas, derivadas de los métodos de JotformAPIClient y adiciones personalizadas. Consulta la documentación de la API de JotForm para obtener detalles sobre parámetros y valores de retorno de las llamadas API subyacentes, a menos que se especifique lo contrario para herramientas personalizadas.

Herramientas de usuario:

  • get_user: Obtener detalles de la cuenta de usuario.
  • get_usage: Obtener estadísticas de uso mensual (envíos, cargas).
  • get_submissions: Obtener una lista de envíos para la cuenta (paginada, filtrable).
  • get_subusers: Obtener una lista de subusuarios.
  • get_settings: Obtener la configuración del usuario (zona horaria, idioma).
  • update_settings: Actualizar la configuración del usuario.
  • get_history: Obtener el registro de actividad del usuario.
  • register_user: Registrar un nuevo usuario (usar con precaución).
  • login_user: Iniciar sesión de usuario (usar con precaución).
  • logout_user: Cerrar sesión de usuario.

Herramientas de formularios:

  • get_forms: Obtener una lista de formularios para la cuenta (paginada, filtrable).
  • get_form: Obtener información básica sobre un formulario específico.
  • get_form_questions: Obtener una lista de todas las preguntas de un formulario.
  • get_form_question: Obtener detalles sobre una pregunta específica.
  • create_form: Crear un nuevo formulario.
  • create_forms: Crear múltiples formularios nuevos (PUT).
  • delete_form: Eliminar un formulario específico.
  • clone_form: Clonar un solo formulario.
  • delete_form_question: Eliminar una sola pregunta de formulario.
  • create_form_question: Agregar una nueva pregunta a un formulario.
  • create_form_questions: Agregar múltiples preguntas nuevas a un formulario (PUT).
  • edit_form_question: Agregar o editar propiedades de una sola pregunta.
  • get_form_properties: Obtener todas las propiedades de un formulario.
  • get_form_property: Obtener una propiedad específica de un formulario.
  • set_form_properties: Agregar o editar propiedades de un formulario (POST).
  • set_multiple_form_properties: Agregar o editar múltiples propiedades de un formulario (PUT).
  • get_form_files: Listar archivos subidos a un formulario.
  • get_form_webhooks: Obtener lista de webhooks para un formulario.
  • create_form_webhook: Agregar un nuevo webhook a un formulario.
  • delete_form_webhook: Eliminar un webhook específico de un formulario.
  • get_form_reports: Obtener todos los informes asociados a un formulario.
  • create_report: Crear un nuevo informe para un formulario.

Herramientas de envíos:

  • get_form_submissions: Listar envíos para un formulario específico (paginado, filtrable).
  • create_form_submission: Enviar datos a un formulario específico.
  • create_form_submissions: Enviar múltiples entradas de datos a un formulario (PUT).
  • get_submission: Obtener datos para un envío específico.
  • delete_submission: Eliminar un solo envío.
  • edit_submission: Editar un solo envío.

Herramientas de carpetas:

  • get_folders: Obtener una lista de carpetas de formularios.
  • get_folder: Obtener detalles de una carpeta específica.
  • create_folder: Crear una nueva carpeta.
  • delete_folder: Eliminar una carpeta específica y sus subcarpetas.
  • update_folder: Actualizar propiedades de una carpeta específica.
  • add_forms_to_folder: Agregar múltiples formularios a una carpeta.
  • add_form_to_folder: Agregar un formulario específico a una carpeta.

Herramientas de informes:

  • get_reports: Listar todos los informes de la cuenta.
  • get_report: Obtener detalles de un informe específico.
  • delete_report: Eliminar un informe específico.
  • (Nota: create_report está listado en Herramientas de formularios)

Herramientas del sistema:

  • get_plan: Obtener detalles de un plan específico de Jotform (por ejemplo, FREE, PREMIUM).

Herramientas personalizadas:

  • search_submissions_by_date:
    • Busca envíos en los formularios especificados (o todos los formularios habilitados si no se especifica ninguno) según un rango de fechas o un período predefinido.
    • Argumentos:
      • form_ids (Opcional List[str]): Lista de IDs de formularios. Por defecto, todos los formularios habilitados.
      • start_date (Opcional str): Fecha de inicio "YYYY-MM-DD" (inclusive). Usar con end_date.
      • end_date (Opcional str): Fecha de fin "YYYY-MM-DD" (inclusive). Usar con start_date.
      • period (Opcional str): Período relativo ("today", "last_7_days", "last_30_days", "current_month", "last_month", "current_accounting_month", "last_accounting_month"). No se puede usar con fechas específicas. Usa ACCOUNTING_MONTH_START_DAY de .env para períodos contables.
      • limit_per_form (Opcional int): Máximo de envíos por formulario (por defecto 1000).
    • Devuelve: Cadena JSON con una lista de envíos y detalles de búsqueda.

Uso original del cliente Python

El archivo jotform.py aún contiene la clase JotformAPIClient, que proporciona acceso directo a los métodos de la API de JotForm dentro de scripts de Python. Puedes importar y usar esta clase directamente si es necesario, aunque la forma principal de interactuar con este proyecto ahora está destinada a ser a través del servidor MCP. Consulta el historial original del README o la documentación de la API de JotForm para ejemplos de uso directo del cliente.