JotForm API - Python Client & MCP Server Adapter

This repository houses the foundational Python client library for interfacing with the JotForm REST API alongside a specialized MCP (Model Context Protocol) intermediary service built atop this client. This service translates generalized MCP tool calls into specific Jotform operations.

Deployment via Smithery (Recommended Approach)

Installation is streamlined through the Smithery registry. Compatible MCP clients (such as Windsurf) can discover and deploy this service easily:

1. Discovery: Navigate to the server management console within your MCP client.
2. Locate: Search for the service descriptor: @The-AI-Workshops/jotform-mcp-server.
3. Deployment: Initiate installation.
4. Initialization: The system will prompt for necessary runtime variables. The paramount requirement is:
   • JOTFORM_API_KEY: Your unique Jotform authentication credential.

Smithery manages environment provisioning (Docker or native Python environments) based on the manifest.

Configuration for Stdio Transport Clients (e.g., Claude Desktop)

To launch the service using standard input/output channels, configure your client as follows:

Method 1: Utilizing Smithery CLI

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

Method 2: Direct Python Invocation

Unix-like Systems (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"
      }
    }
  }
}

Method 3: Utilizing a Virtual Environment

Unix-like Systems:

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

Method 4: Execution via uv (Modern Python Runtime)

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

Credential Management

Access to JotForm API endpoints that manage user-specific resources mandates the use of an API key. These keys are generated within the API management section of your JotForm user dashboard. This key is essential regardless of whether deployment is manual or automated via Smithery.

Local Development Setup Guide

Automated Deployment via Smithery

For seamless integration with desktop clients like Claude, use the Smithery command-line utility:

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

1. Obtain Source Code:

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

2. Environment Isolation (Recommended Practice):

python3 -m venv venv
source venv/bin/activate  # Use `venv\Scripts\activate` on Windows

3. Dependency Resolution:

Select the appropriate dependency installation method:

• Using uv (Preferred for speed/reproducibility):

  • If uv is absent, install it: pip install uv
  • Synchronize dependencies using the lock file: bash uv pip sync uv.lock

• Using pip (Traditional):

  • Install listed dependencies: bash pip install -r requirements.txt

4. Credential Injection:

• Rename the template file: .env.example to .env.
• Edit .env, replacing the placeholder with your actual API token.
• Optional: Configure port (MCP_PORT), base URL, or transport type.

# .env configuration file
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 Setting for Date-Based Queries
ACCOUNTING_MONTH_START_DAY="1" # Defines the first day for 'current_accounting_month' queries

5. Service Launch:

Ensure the virtual environment is active, then execute:

python jotform_mcp_server.py

The server initiates, typically binding to port 8067. All public interfaces of the JotformAPIClient are exposed as MCP tools.

Containerized Execution (Docker)

A Dockerfile is supplied for containerization.

1. Image Creation:

Execute this command from the project root:

docker build -t jotform-mcp-server .

2. Container Instantiation:

You must supply the API key via environment variables during execution.

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

• -d: Detached mode.
• -p 8067:8067: Port mapping.
• -e JOTFORM_API_KEY="...": Essential credential passing.

Management Commands:

• View Output: docker logs jotform-server
• Halt: docker stop jotform-server
• Remove: docker rm jotform-server

Connecting with MCP Consumers

This gateway supports various connection modalities used by MCP clients (e.g., Windsurf, n8n).

Server-Sent Events (SSE) Configuration

If running natively or via Docker with port forwarding (as shown above), use SSE. Verify TRANSPORT=sse in your environment configuration.

Generic MCP Setup:

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

(When connecting from another containerized service, replace localhost with host.docker.internal.)

Python Local Process (Stdio) Configuration

This relies on the client managing the lifecycle of the Python interpreter. Replace placeholders with absolute file system paths.

{
  "mcpServers": {
    "jotform": {
      "command": "your/path/to/jotform-mcp-server/venv/bin/python", // Windows: venv\Scripts\python.exe
      "args": ["your/path/to/jotform-mcp-server/jotform_mcp_server.py"],
      "env": {
        "TRANSPORT": "stdio",
        "JOTFORM_API_KEY": "YOUR_ACTUAL_JOTFORM_API_KEY"
        // Other overrides are possible here
      }
    }
  }
}

Docker Stdio Configuration

Allows the client to invoke the container as a transient process.

{
  "mcpServers": {
    "jotform": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-e", "TRANSPORT=stdio",
               "-e", "JOTFORM_API_KEY", // Inherits from 'env' block
               "jotform-mcp-server:latest" // Use built image tag
              ],
      "env": {
        "TRANSPORT": "stdio",
        "JOTFORM_API_KEY": "YOUR_ACTUAL_JOTFORM_API_KEY"
      }
    }
  }
}

Expedited Execution Method

For rapid testing without formal setup, provided Python 3.11+ and Git are available:

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

# 2. Environment Setup (Temporary .env)
echo "JOTFORM_API_KEY=YOUR_ACTUAL_JOTFORM_API_KEY" > .env

# 3. Run (Using uv for dependencies)
pip install uv && uv pip sync uv.lock && python jotform_mcp_server.py

# Stop with CTRL+C. Clean up with `cd .. && rm -rf jotform-mcp-server`

Exposed Tool Definitions

This gateway exposes functionalities mirroring the JotformAPIClient methods, augmented by specialized workflow tools. Consult the JotForm API documentation for upstream parameter specifications.

Account Management Tools: * get_user: Retrieve account metadata. * get_usage: Fetch current month's data consumption statistics. * get_submissions: Fetch account-wide submissions (supports filtering/pagination). * get_subusers: List associated sub-user accounts. * get_settings: Retrieve current user configuration (e.g., locale). * update_settings: Modify user configuration parameters. * get_history: Access the audit log. * register_user, login_user, logout_user: User lifecycle operations (use with prudence).

Form Structure & Metadata Tools: * get_forms: List all forms owned by the account. * get_form: Fetch specific form details. * get_form_questions: Enumerate all fields within a form. * get_form_question: Detail a single field. * create_form, create_forms: Instantiate new form entities. * delete_form: Retire a form. * clone_form: Duplicate an existing form. * delete_form_question, create_form_question, create_form_questions, edit_form_question: Field modification utilities. * get_form_properties, get_form_property, set_form_properties, set_multiple_form_properties: Form attribute manipulation. * get_form_files: Inventory files attached to a form. * get_form_webhooks, create_form_webhook, delete_form_webhook: Webhook endpoint management. * get_form_reports, create_report: Report generation linkage.

Data Payload Tools (Submissions): * get_form_submissions: Retrieve entries for a specific form. * create_form_submission, create_form_submissions: Inject new data records into a form. * get_submission: Inspect a singular submission payload. * delete_submission: Remove an entry. * edit_submission: Modify an existing submission record.

Organizational Tools (Folders): * get_folders, get_folder: Directory listing and detail retrieval. * create_folder: Establish a new folder grouping. * delete_folder: Remove a folder and its contents. * update_folder: Rename or reposition a folder. * add_forms_to_folder, add_form_to_folder: Assign forms to organizational units.

Analytical Assets: * get_reports: Retrieve all defined reports. * get_report: Detail a specific report configuration. * delete_report: Remove an existing report asset.

System Utilities: * get_plan: Query information pertaining to the active subscription tier (e.g., BRONZE, SILVER).

Custom Workflow Tool: * search_submissions_by_date: * A utility for aggregating submission data across specified forms or all active forms within a defined temporal window. * Parameters: * form_ids (Optional List): Explicit list of form identifiers. If absent, all forms are scanned. * start_date (Optional String): Start boundary in 'YYYY-MM-DD' format (inclusive). * end_date (Optional String): End boundary in 'YYYY-MM-DD' format (inclusive). * period (Optional String): Relative time designator ("today", "last_7_days", "current_accounting_month", etc.). Mutually exclusive with date range specification. Accounting periods utilize the ACCOUNTING_MONTH_START_DAY environment variable. * limit_per_form (Optional Integer): Upper bound on records retrieved from any single form (default 1000). * Output: A serialized JSON structure detailing the retrieved records and the query parameters used.

Legacy Python Client Interaction

The original jotform.py module remains intact, offering the JotformAPIClient class for direct invocation within Python scripts. Interaction via the MCP layer is now prioritized, but direct client use remains supported.