JotForm

Um servidor MCP para interagir com a API do Jotform para gerenciar formulários online e envios.

GitHub
1
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge Verified on MseeP

API JotForm - Cliente Python e Servidor MCP

smithery badge

Este repositório contém o cliente Python para a API JotForm e um servidor MCP (Model Context Protocol) construído usando este cliente. O servidor MCP permite interação com a API Jotform por meio de ferramentas padronizadas.

Instalação via Smithery (Recomendado para Clientes MCP)

Este servidor está disponível no Smithery. Você pode instalá-lo e configurá-lo facilmente em clientes MCP compatíveis (como Windsurf):

  1. Pesquisar: Na interface de gerenciamento de servidores do seu cliente MCP, pesquise por servidores.
  2. Encontrar: Procure por JotForm API Server ou use o ID @The-AI-Workshops/jotform-mcp-server.
  3. Instalar: Selecione o servidor e clique em "Instalar".
  4. Configurar: Após a instalação, você será solicitado a configurar as variáveis de ambiente necessárias. A mais importante é:
    • JOTFORM_API_KEY: Sua chave de API Jotform.

O Smithery gerencia a configuração subjacente (ambiente Docker ou Python) com base na configuração do servidor.

Configuração para Claude Desktop e Clientes MCP Semelhantes

Para Claude Desktop e outros clientes MCP que usam transporte stdio, você pode configurar o servidor de várias maneiras:

Opção 1: CLI Smithery (Windows/Plataforma cruzada)

{
  "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\\\"}\""
      ]
    }
  }
}

Opção 2: Execução Direta em 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"
      }
    }
  }
}

Opção 3: Usando Ambiente 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"
      }
    }
  }
}

Opção 4: Usando uv (Recomendado para ambientes 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"
      }
    }
  }
}

Autenticação

A API JotForm requer uma chave de API para todas as chamadas relacionadas ao usuário. Você pode criar suas chaves de API na seção de API das configurações da sua conta JotForm. Esta chave é necessária para executar o servidor MCP, seja instalado manualmente ou via Smithery.

Configuração Manual e Execução (para Desenvolvimento ou Uso sem Smithery)

Instalação via Smithery

Para instalar o Servidor API JotForm para Claude Desktop automaticamente via Smithery:

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

1. Clonar o Repositório:

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

2. Criar Ambiente Virtual (Recomendado):

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

3. Instalar Dependências:

Escolha um dos seguintes métodos:

  • Usando uv (Recomendado):

    • Se você não tiver o uv, instale-o: pip install uv
    • Instale as dependências usando o arquivo de bloqueio para reprodutibilidade: 
      uv pip sync uv.lock

  • Usando pip:

    • Instale as dependências usando o arquivo requirements.txt: 
      pip install -r requirements.txt

4. Configurar Chave de API:

  • Renomeie o arquivo .env.example para .env.
  • Abra o arquivo .env e substitua "YOUR_JOTFORM_API_KEY_HERE" pela sua chave de API Jotform real.
  • Você também pode ajustar outras configurações como MCP_PORT ou JOTFORM_BASE_URL se necessário.
# .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. Executar o Servidor:

Certifique-se de que seu ambiente virtual está ativado.

python jotform_mcp_server.py

O servidor iniciará, normalmente escutando na porta http://0.0.0.0:8067. Você pode então conectar-se a ele usando um cliente MCP. Todos os métodos públicos do JotformAPIClient são expostos como ferramentas.

Executando com Docker

Um Dockerfile é fornecido para containerizar o servidor MCP.

1. Construir a Imagem Docker:

Certifique-se de estar no diretório raiz do projeto (onde o Dockerfile está localizado).

docker build -t jotform-mcp-server .

2. Executar o Container Docker:

Você deve fornecer sua chave de API Jotform como uma variável de ambiente ao executar o container.

docker run -d -p 8067:8067 -e JOTFORM_API_KEY="YOUR_ACTUAL_JOTFORM_API_KEY" --name jotform-server jotform-mcp-server
  • -d: Executa o container em modo destacado (em segundo plano).
  • -p 8067:8067: Mapeia a porta 8067 do seu host para a porta 8067 no container.
  • -e JOTFORM_API_KEY="...": Crucialmente, passe sua chave de API aqui.
  • --name jotform-server: Atribui um nome ao container para gerenciamento mais fácil.
  • jotform-mcp-server: O nome da imagem que você construiu.

O servidor MCP estará rodando dentro do container e acessível na porta 8067 da sua máquina host.

Para visualizar logs:

docker logs jotform-server

Para parar o container:

docker stop jotform-server

Para remover o container:

docker rm jotform-server

Integração com Clientes MCP

Você pode conectar-se a este servidor usando qualquer cliente compatível com MCP (como Windsurf, Claude Desktop, n8n, etc.). Aqui estão exemplos de configurações para diferentes métodos de transporte:

Configuração SSE

Se você executar o servidor diretamente (python jotform_mcp_server.py) ou usando Docker com mapeamento de porta (como mostrado acima), você pode conectar via SSE. Certifique-se de que TRANSPORT=sse está definido no seu arquivo .env ou passado para o container Docker.

Configuração MCP Padrão:

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

Configuração Windsurf:

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

(Nota: Se conectar de outro container Docker, como n8n, substitua localhost por host.docker.internal)

Configuração Python com Stdio

Isso permite que o cliente MCP gerencie o processo do servidor diretamente usando seu ambiente Python local. Substitua your/path/to/ pelo caminho absoluto real para o diretório do projeto.

{
  "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"
      }
    }
  }
}

Configuração Docker com Stdio

Isso permite que o cliente MCP gerencie o processo do servidor rodando dentro de um container Docker. Certifique-se de ter construído a imagem (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"
      }
    }
  }
}

Execução Rápida (semelhante a npx)

Se você quiser executar o servidor rapidamente sem uma configuração local completa (semelhante a como npx funciona para pacotes Node.js), você pode combinar as etapas. Isso é útil para execução temporária ou testes.

Certifique-se de ter Python 3.11+ e 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 pode instalar dependências globalmente se você não estiver dentro de um ambiente virtual ativado. Usar um ambiente virtual dedicado (Etapas 2 e 3 na configuração principal) ou Docker é recomendado para melhor isolamento do projeto.

Ferramentas Disponíveis

Este servidor expõe as seguintes ferramentas, derivadas dos métodos do JotformAPIClient e adições personalizadas. Consulte a documentação da API JotForm para detalhes sobre parâmetros e valores de retorno para as chamadas de API subjacentes, salvo indicação em contrário para ferramentas personalizadas.

Ferramentas de Usuário:

  • get_user: Obter detalhes da conta do usuário.
  • get_usage: Obter estatísticas de uso mensal (envios, uploads).
  • get_submissions: Obter uma lista de envios para a conta (paginada, filtrável).
  • get_subusers: Obter uma lista de subusuários.
  • get_settings: Obter configurações do usuário (fuso horário, idioma).
  • update_settings: Atualizar configurações do usuário.
  • get_history: Obter log de atividade do usuário.
  • register_user: Registrar um novo usuário (usar com cautela).
  • login_user: Login de usuário (usar com cautela).
  • logout_user: Logout de usuário.

Ferramentas de Formulário:

  • get_forms: Obter uma lista de formulários para a conta (paginada, filtrável).
  • get_form: Obter informações básicas sobre um formulário específico.
  • get_form_questions: Obter uma lista de todas as perguntas em um formulário.
  • get_form_question: Obter detalhes sobre uma pergunta específica.
  • create_form: Criar um novo formulário.
  • create_forms: Criar múltiplos novos formulários (PUT).
  • delete_form: Excluir um formulário específico.
  • clone_form: Clonar um único formulário.
  • delete_form_question: Excluir uma única pergunta de formulário.
  • create_form_question: Adicionar uma nova pergunta a um formulário.
  • create_form_questions: Adicionar múltiplas novas perguntas a um formulário (PUT).
  • edit_form_question: Adicionar ou editar propriedades de uma única pergunta.
  • get_form_properties: Obter todas as propriedades de um formulário.
  • get_form_property: Obter uma propriedade específica de um formulário.
  • set_form_properties: Adicionar ou editar propriedades de um formulário (POST).
  • set_multiple_form_properties: Adicionar ou editar múltiplas propriedades de um formulário (PUT).
  • get_form_files: Listar arquivos enviados para um formulário.
  • get_form_webhooks: Obter lista de webhooks para um formulário.
  • create_form_webhook: Adicionar um novo webhook a um formulário.
  • delete_form_webhook: Excluir um webhook específico de um formulário.
  • get_form_reports: Obter todos os relatórios associados a um formulário.
  • create_report: Criar um novo relatório para um formulário.

Ferramentas de Envio:

  • get_form_submissions: Listar envios para um formulário específico (paginado, filtrável).
  • create_form_submission: Enviar dados para um formulário específico.
  • create_form_submissions: Enviar múltiplas entradas de dados para um formulário (PUT).
  • get_submission: Obter dados para um envio específico.
  • delete_submission: Excluir um único envio.
  • edit_submission: Editar um único envio.

Ferramentas de Pasta:

  • get_folders: Obter uma lista de pastas de formulários.
  • get_folder: Obter detalhes de uma pasta específica.
  • create_folder: Criar uma nova pasta.
  • delete_folder: Excluir uma pasta específica e suas subpastas.
  • update_folder: Atualizar propriedades de uma pasta específica.
  • add_forms_to_folder: Adicionar múltiplos formulários a uma pasta.
  • add_form_to_folder: Adicionar um formulário específico a uma pasta.

Ferramentas de Relatório:

  • get_reports: Listar todos os relatórios para a conta.
  • get_report: Obter detalhes de um relatório específico.
  • delete_report: Excluir um relatório específico.
  • (Nota: create_report está listado em Ferramentas de Formulário)

Ferramentas de Sistema:

  • get_plan: Obter detalhes de um plano Jotform específico (ex.: FREE, PREMIUM).

Ferramentas Personalizadas:

  • search_submissions_by_date:
    • Pesquisa envios em formulários especificados (ou todos os formulários habilitados se nenhum for especificado) com base em um intervalo de datas ou um período predefinido.
    • Argumentos:
      • form_ids (Opcional List[str]): Lista de IDs de formulários. Padrão para todos os formulários habilitados.
      • start_date (Opcional str): Data de início "AAAA-MM-DD" (inclusiva). Use com end_date.
      • end_date (Opcional str): Data de fim "AAAA-MM-DD" (inclusiva). Use com 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"). Não pode ser usado com datas específicas. Usa ACCOUNTING_MONTH_START_DAY de .env para períodos contábeis.
      • limit_per_form (Opcional int): Máximo de envios por formulário (padrão 1000).
    • Retorna: String JSON com uma lista de envios e detalhes da pesquisa.

Uso Original do Cliente Python

O arquivo jotform.py ainda contém a classe JotformAPIClient, que fornece acesso direto aos métodos da API JotForm em scripts Python. Você pode importar e usar esta classe diretamente se necessário, embora a principal forma de interagir com este projeto agora seja através do servidor MCP. Consulte o histórico do README original ou a documentação da API JotForm para exemplos de uso direto do cliente.