JotForm API Server

](https://mseep.ai/app/the-ai-workshops-jotform-mcp-server) 

JotForm API-Python客户端和MCP服务器

](https://smithery.ai/server/@The-AI-Workshops/jotform-mcp-server)

此存储库包含Python客户端 JotForm API 以及使用该客户端构建的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客户端的配置

对于Claude Desktop和其他使用stdio传输的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"
      }
    }
  }
}

窗户：

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

窗户：

{
  "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密钥。您可以在 API部分 您的JotForm帐户设置。运行MCP服务器需要此密钥，无论是手动安装还是通过Smithery安装。

手动设置和运行（用于开发或非史密斯工厂使用）

通过Smithery安装

通过自动安装JotForm API Server for Claude Desktop 史密瑟里:

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运行

A. 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映射到容器中的端口8066。
• -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连接。确保 TRANSPORT=sse 设置在您的 .env 文件或传递到Docker容器。

*标准MCP配置：*

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

*风帆配置：*

{
  "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：获取表单的webhooks列表。
• 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计划的详细信息（例如，免费、高级）。

自定义工具：

• 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)：相对周期（“今天”、“过去7天”、“最近30天”、”当前月“、”过去月“、“当前计数月”、“最后计数月”）。不能与特定日期一起使用。用途 ACCOUNTING_MONTH_START_DAY 从 .env 会计期间。 - limit_per_form （可选 int)：每个表单的最大提交量（默认值为1000）。 - 退货： JSON字符串，包含提交列表和搜索详细信息。

原始Python客户端用法

这 jotform.py 文件仍然包含 JotformAPIClient 类，它提供了对Python脚本中JotForm的API方法的直接访问。如果需要，您可以直接导入和使用此类，尽管现在与此项目交互的主要方式是通过MCP服务器。请参阅原始README历史记录或 JotForm API文件 例如直接客户端使用。