jotform-connector-mcp-gateway

MCP Server for JotForm Data Orchestration

This repository furnishes a Python-based service layer, operating under the Model Context Protocol (MCP), to interface seamlessly with the comprehensive JotForm Application Programming Interface (API). It centralizes management of user accounts, form definitions, collected responses, organizational structures (folders), and analytical outputs (reports) via a unified interface.

---

Deployment & Configuration Guide

This service is accessible and deployable via several mechanisms, highly favoring the Smithery ecosystem for simplified orchestration.

Smithery Integration (Preferred MCP Client Setup)

To deploy this service instance into environments compatible with Smithery (e.g., Windsurf clients), utilize the following identifier:

• Server ID: @The-AI-Workshops/jotform-mcp-server

Installation involves searching for this ID within your client's server manager, followed by providing runtime configuration via environment variables. The critical credential required is:

• JOTFORM_API_KEY: Securely provisioned key from your Jotform developer settings.

Smithery manages the containerization (Docker) or environment setup (Python runtime) automatically.

Local Client Configuration (e.g., Claude Desktop via stdio)

When direct process control is necessary (like standard I/O transport for local execution), configuration files need to specify the execution path and environmental context.

Example Configuration Snippet (Generic stdio):

{
  "mcpServers": {
    "jotform_interface": {
      "command": "python", 
      "args": ["/path/to/your/server/entrypoint.py"], 
      "env": {
        "JOTFORM_API_KEY": "YOUR_SECURE_API_KEY",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Detailed examples for Windows, Linux, and specialized runners like npx or uv are provided in the original repository documentation.

Access Credentials

All non-read operations targeting account-specific data mandate the use of a valid JotForm API access token. These tokens are generated and managed within the 'API' section of your JotForm administrative panel. This key must be supplied to the server process via the JOTFORM_API_KEY environment variable during startup.

Development & Manual Startup Procedures

For environments without Smithery integration, manual setup is required.

1. Source Code Acquisition:

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

2. Environment Isolation (Highly Recommended):

python3 -m venv isolation_env
source isolation_env/bin/activate  # Linux/macOS
# or venv\Scripts\activate on Windows

3. Dependency Resolution:

• Modern Resolver (uv): bash pip install uv uv pip sync uv.lock
• Traditional Resolver (pip): bash pip install -r requirements.txt

4. Parameter Initialization (.env File):

Create and populate a .env file to define runtime parameters. Key settings include:

# .env
JOTFORM_API_KEY="YOUR_ACTUAL_JOTFORM_API_KEY"
MCP_HOST="0.0.0.0"
MCP_PORT="8067"
MCP_TRANSPORT="sse" 
# Custom accounting logic setting
ACCOUNTING_MONTH_START_DAY="1"

5. Server Activation:

python jotform_mcp_server.py

The service will initialize, usually binding to port 8067, ready for external MCP connections. The exposed tools mirror the functionalities of the underlying JotformAPIClient.

Containerized Deployment (Docker)

To ensure environment parity, containerization is supported via the provided Dockerfile.

1. Image Construction:

Execute this command from the root directory containing the Dockerfile:

docker build -t jotform-mcp-server .

2. Instance Execution:

Startup requires the API key to be securely injected as an environment variable:

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

• Log Access: docker logs jf_gateway
• Termination: docker stop jf_gateway

Interoperability with Consuming Agents

Connection methods depend on the server's operational mode (SSE listening or Stdio management).

SSE Connection (HTTP Polling Mode):

Used when the server runs independently (Docker or direct Python execution).

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

Stdio Connection (Process Management Mode):

Used when the MCP client initiates and controls the server process lifecycle. Ensure paths in the command and args fields are absolute and correct for the target execution context.

{
  "mcpServers": {
    "jotform_stdio": {
      "command": "/path/to/venv/bin/python", 
      "args": ["/path/to/server/jotform_mcp_server.py"],
      "env": { 
        "TRANSPORT": "stdio",
        "JOTFORM_API_KEY": "YOUR_ACTUAL_JOTFORM_API_KEY"
      }
    }
  }
}

Exposed Tool Definitions

All methods available in the internal JotformAPIClient are mapped to MCP tools. Notable custom utilities include:

• search_submissions_by_date: Aggregates submissions across specified forms within defined date boundaries or relative periods (e.g., 'last_30_days'). Utilizes the .env variable ACCOUNTING_MONTH_START_DAY for custom monthly period calculations.

Tool Categories:

Category	Key Operations Exposed
User Management	Retrieve account metrics, usage statistics, settings, and activity logs.
Form Structure	Create, retrieve, update, and discard forms and their constituent question elements.
Data Retrieval	Fetch submission records (per form or account-wide), including filtering and pagination support.
Data Ingestion	Tools to programmatically inject new submission payloads.
Folder Organization	Manage hierarchical grouping of forms.
Reporting	Access or generate specific analytical reports linked to forms.

For parameter specifications of any given tool, consult the documentation for the underlying JotformAPIClient methods.