JotForm API - Python Client & MCP Server

JotForm API - Python Client & MCP Server

このリポジトリには、JotForm API 用の Python クライアントと、このクライアントを使用して構築された MCP（Model Context Protocol）サーバーが含まれています。MCP サーバーを使用すると、標準化されたツールを通じて Jotform API を利用できます。

Smithery 経由でのインストール（MCP クライアント向け推奨）

このサーバーは Smithery で利用できます。対応する MCP クライアント（Windsurf など）内で簡単にインストールして設定できます。

1. 検索： MCP クライアントのサーバー管理画面で、サーバーを検索します。
2. 確認： JotForm API Server を探すか、ID @The-AI-Workshops/jotform-mcp-server を使用します。
3. インストール： サーバーを選択し、「Install」をクリックします。
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 経由で JotForm API Server を 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. 依存関係をインストール：

次の方法から1つ選択してください。

• 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 での実行

MCP サーバーをコンテナ化するための Dockerfile が用意されています。

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

(注：n8n のような別の Docker コンテナから接続する場合は、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 のような方法）

ローカル環境を完全にセットアップせずにサーバーをすばやく実行したい場合（Node.js パッケージで npx を使う場合と同様）は、手順を組み合わせて実行できます。一時的な実行やテストに便利です。

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 のメソッドとカスタム追加機能を基に、以下のツールを公開します。カスタムツールについて個別の指定がない限り、基盤となる API 呼び出しのパラメーターと戻り値の詳細は、JotForm 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：フォームを1つ複製します。
• delete_form_question：フォームの質問を1つ削除します。
• create_form_question：フォームに新しい質問を追加します。
• create_form_questions：フォームに複数の新しい質問を追加します（PUT）。
• edit_form_question：1つの質問のプロパティを追加または編集します。
• 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：送信データを1件削除します。
• edit_submission：送信データを1件編集します。

フォルダーツール：

• 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 ファイルには、Pythonスクリプト内からJotFormのAPIメソッドに直接アクセスできる JotformAPIClient クラスが引き続き含まれています。必要に応じてこのクラスを直接インポートして使用できますが、このプロジェクトを利用する主な方法は、MCP サーバーを介する形を想定しています。直接クライアントを使用する例については、以前のREADMEの履歴、またはJotForm APIドキュメントを参照してください。