JotForm API - Python Client & MCP Server

JotForm API - Python 客户端与 MCP 服务

此仓库包含 JotForm API 的 Python 客户端，以及基于该客户端构建的 MCP（模型上下文协议）服务。此 MCP 服务允许通过标准化工具与 Jotform API 交互。

通过 Smithery 安装（推荐用于 MCP 客户端）

此服务已在 Smithery 上提供。你可以在兼容的 MCP 客户端（如 Windsurf）中轻松安装并配置：

1. 搜索： 在 MCP 客户端的服务管理界面中搜索服务。
2. 查找： 查找 JotForm API Server，或使用 ID @The-AI-Workshops/jotform-mcp-server。
3. 安装： 选择该服务并点击“安装”。
4. 配置： 安装后，系统会提示你配置所需的环境变量。最重要的是：
   • JOTFORM_API_KEY：你的 Jotform API 密钥。

Smithery 会根据服务的配置处理底层设置（Docker 或 Python 环境）。

Claude Desktop 和类似 MCP 客户端的配置

对于使用 stdio 传输的 Claude Desktop 和其他 MCP 客户端，你可以通过多种方式配置服务：

选项 1：Smithery CLI（Windows/跨平台）

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

选项 2：直接运行 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"
      }
    }
  }
}

选项 3：使用虚拟环境

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

选项 4：使用 uv（推荐用于 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"
      }
    }
  }
}

身份验证

JotForm API 的所有用户相关调用都需要 API 密钥。你可以在 JotForm 账户设置的 API 部分创建 API 密钥。无论是手动安装还是通过 Smithery 安装，运行 MCP 服务都需要此密钥。

手动设置和运行（用于开发或非 Smithery 场景）

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 JotForm API Server：

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

1. 克隆仓库：

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

2. 创建虚拟环境（推荐）：

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

3. 安装依赖项：

从以下方法中选择一种：

• 使用 uv（推荐）：

  • 如果尚未安装 uv，请安装：pip install uv
  • 使用锁文件安装依赖项，以确保可复现性：

    uv pip sync uv.lock
    

• 使用 pip：

  • 使用 requirements.txt 文件安装依赖项：

    pip install -r requirements.txt
    

4. 配置 API 密钥：

• 将 .env.example 文件重命名为 .env。
• 打开 .env 文件，将 "YOUR_JOTFORM_API_KEY_HERE" 替换为你的实际 Jotform API 密钥。
• 你也可以根据需要调整其他设置，例如 MCP_PORT 或 JOTFORM_BASE_URL。

# .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. 运行服务：

确保已激活虚拟环境。

python jotform_mcp_server.py

服务将启动，通常监听 http://0.0.0.0:8067。随后你可以使用 MCP 客户端连接到它。JotformAPIClient 的所有公共方法都会作为工具公开。

使用 Docker 运行

项目提供了 Dockerfile，用于将 MCP 服务容器化。

1. 构建 Docker 镜像：

确保你位于项目根目录（即 Dockerfile 所在目录）。

docker build -t jotform-mcp-server .

2. 运行 Docker 容器：

运行容器时，必须将 Jotform API 密钥作为环境变量提供。

docker run -d -p 8067:8067 -e JOTFORM_API_KEY="YOUR_ACTUAL_JOTFORM_API_KEY" --name jotform-server jotform-mcp-server

• -d：在后台以分离模式运行容器。
• -p 8067:8067：将主机上的端口 8067 映射到容器内的端口 8067。
• -e JOTFORM_API_KEY="..."：重要，在此处传入 API 密钥。
• --name jotform-server：为容器指定名称，以便于管理。
• jotform-mcp-server：你构建的镜像名称。

MCP 服务将在容器内运行，并可通过主机上的端口 8067 访问。

查看日志：

docker logs jotform-server

停止容器：

docker stop jotform-server

删除容器：

docker rm jotform-server

与 MCP 客户端集成

你可以使用任何兼容 MCP 的客户端（如 Windsurf、Claude Desktop、n8n 等）连接到此服务。以下是不同传输方式的配置示例：

SSE 配置

如果你直接运行服务（python jotform_mcp_server.py），或使用 Docker 并映射端口（如上所示），就可以通过 SSE 连接。请确保在 .env 文件中设置 TRANSPORT=sse，或将其传递给 Docker 容器。

标准 MCP 配置：

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

Windsurf 配置：

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

（注意：如果从另一个 Docker 容器（如 n8n）连接，请将 localhost 替换为 host.docker.internal）

使用 Stdio 的 Python 配置

此配置允许 MCP 客户端使用本地 Python 环境直接管理服务进程。请将 your/path/to/ 替换为项目目录的实际绝对路径。

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

使用 Stdio 的 Docker 配置

此配置允许 MCP 客户端管理在 Docker 容器内运行的服务进程。请确保已构建镜像（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"
      }
    }
  }
}

快速运行（类似 npx）

如果你想快速运行服务，而不进行完整的本地设置（类似于 npx 运行 Node.js 包的方式），可以合并这些步骤。这适用于临时运行或测试。

确保已安装 Python 3.11+ 和 git。

# 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

注意： 如果你未在已激活的虚拟环境中，此方法可能会全局安装依赖项。建议使用专用虚拟环境（主设置中的步骤 2 和 3）或 Docker，以实现更好的项目隔离。

可用工具

此服务提供以下工具，这些工具基于 JotformAPIClient 方法及自定义扩展。除非自定义工具另有说明，请参阅 JotForm API 文档，了解底层 API 调用的参数和返回值详情。

用户工具：

• get_user：获取用户账户详情。
• get_usage：获取每月用量统计（提交数、上传数）。
• get_submissions：获取账户的提交列表（支持分页和筛选）。
• get_subusers：获取子用户列表。
• get_settings：获取用户设置（时区、语言）。
• update_settings：更新用户设置。
• get_history：获取用户活动日志。
• register_user：注册新用户（谨慎使用）。
• login_user：登录用户（谨慎使用）。
• logout_user：退出用户登录。 表单工具：
• get_forms：获取账户的表单列表（支持分页和筛选）。
• get_form：获取特定表单的基本信息。
• get_form_questions：获取表单中所有问题的列表。
• get_form_question：获取特定问题的详细信息。
• create_form：创建新表单。
• create_forms：创建多个新表单（PUT）。
• delete_form：删除特定表单。
• clone_form：克隆单个表单。
• delete_form_question：删除单个表单问题。
• create_form_question：向表单添加新问题。
• create_form_questions：向表单添加多个新问题（PUT）。
• edit_form_question：添加或编辑单个问题的属性。
• get_form_properties：获取表单的所有属性。
• get_form_property：获取表单的特定属性。
• set_form_properties：添加或编辑表单属性（POST）。
• set_multiple_form_properties：添加或编辑多个表单属性（PUT）。
• get_form_files：列出上传到表单的文件。
• get_form_webhooks：获取表单的 Webhook 列表。
• create_form_webhook：向表单添加新 Webhook。
• delete_form_webhook：删除表单的特定 Webhook。
• get_form_reports：获取与表单关联的所有报告。
• create_report：为表单创建新报告。

提交工具：

• get_form_submissions：列出特定表单的提交记录（支持分页和筛选）。
• create_form_submission：向特定表单提交数据。
• create_form_submissions：向表单提交多条数据（PUT）。
• get_submission：获取特定提交记录的数据。
• delete_submission：删除单条提交记录。
• edit_submission：编辑单条提交记录。

文件夹工具：

• get_folders：获取表单文件夹列表。
• get_folder：获取特定文件夹的详细信息。
• create_folder：创建新文件夹。
• delete_folder：删除特定文件夹及其子文件夹。
• update_folder：更新特定文件夹的属性。
• add_forms_to_folder：向文件夹添加多个表单。
• add_form_to_folder：向文件夹添加特定表单。

报告工具：

• get_reports：列出账户的所有报告。
• get_report：获取特定报告的详细信息。
• delete_report：删除特定报告。
• (注意：create_report 列在表单工具下)

系统工具：

• get_plan：获取特定 Jotform 套餐的详细信息（例如 FREE、PREMIUM）。

自定义工具：

• search_submissions_by_date：
  • 根据日期范围或预定义时段，搜索指定表单中的提交记录（如果未指定，则搜索所有已启用的表单）。
  • 参数：
    • form_ids（可选 List[str]）：表单 ID 列表。默认为所有已启用的表单。
    • start_date（可选 str）：开始日期“YYYY-MM-DD”（含）。与 end_date 搭配使用。
    • end_date（可选 str）：结束日期“YYYY-MM-DD”（含）。与 start_date 搭配使用。
    • period（可选 str）：相对时段（"today"、"last_7_days"、"last_30_days"、"current_month"、"last_month"、"current_accounting_month"、"last_accounting_month"）。不可与具体日期同时使用。会使用 .env 中的 ACCOUNTING_MONTH_START_DAY 计算会计周期。
    • limit_per_form（可选 int）：每个表单的提交记录上限（默认 1000）。
  • **返回：**包含提交记录列表和搜索详情的 JSON 字符串。

原始 Python 客户端用法

jotform.py 文件仍包含 JotformAPIClient 类，可在 Python 脚本中直接访问 JotForm 的 API 方法。如有需要，你可以直接导入并使用此类，但现在与本项目交互的主要方式是通过 MCP 服务。有关直接使用客户端的示例，请参阅原始 README 历史记录或 JotForm API 文档。