Zoho Analytics MCP Server

The Zoho Analytics MCP Server (Beta) implements the Model Context Protocol (MCP), a standardized interface that enables AI models to interact seamlessly with applications. This middleware solution bridges the connection between AI agents and Zoho Analytics, providing powerful data analysis capabilities through a unified interface.

Note: The Zoho Analytics MCP project is currently in its early development (Beta) phase. As we continue to improve and refine its features, the available tools and functionalities may change.

Getting Started

1. Docker Image Setup
2. Configuring Environment Variables
3. Remote MCP Server Setup (Hosted Option)
4. Integrating with MCP Hosts
   • Claude Desktop
   • VSCode
   • Cursor

1. Docker Image Setup

System Requirements To build the Zoho Analytics MCP server from source, you need to have Docker installed on your system. Before setup, please make sure to have docker and a container runtime installed in your device.

Pull Docker Image

If you prefer to use the pre-built Docker image, you can pull it directly from Docker Hub:

docker pull zohoanalytics/mcp-server:latest

2. Configuring Environment Variables

Obtaining OAuth Credentials To configure the Zoho Analytics MCP Server, you need to provide OAuth credentials (Client ID, Client Secret, and Refresh Token) as environment variables. Follow these steps to generate them:

1. Go to the Zoho Developer Console
2. Create a new Self-Client application.
3. Enable the Zoho Analytics API scope.
4. Generate your Refresh Token. For detailed instructions, refer to the official API Authentication Documentation.

Required Environment Variables

Configure these essential variables before integrating with the MCP Hosts:

Variable	Description
ANALYTICS_CLIENT_ID	Your Zoho Analytics OAuth client ID
ANALYTICS_CLIENT_SECRET	Your Zoho Analytics OAuth client secret
ANALYTICS_REFRESH_TOKEN	Your Zoho Analytics OAuth refresh token
ANALYTICS_ORG_ID	Your Zoho Analytics organization ID
ANALYTICS_MCP_DATA_DIR	Directory for storing temporary data files
ACCOUNTS_SERVER_URL	Your Zoho Analytics Accounts Domain URL (https://accounts.zoho.com)
ANALYTICS_SERVER_URL	Your Zoho Analytics Accounts Domain URL (https://analyticsapi.zoho.com)

Other Environment variables

The following is a list of other optional environment variables:

QUERY_DATA_RESULT_ROW_LIMITS (Optional)	Number of rows outputted by the query_data tool. Default row limit - 20
QUERY_DATA_POLLING_INTERVAL (Optional)	Sleep Time between consecutive polls to check job status (JOB COMPLETED, JOB IN QUEUE; For more, please refer to analytics v2 api documentation). Default sleep time - 4 seconds
QUERY_DATA_QUEUE_TIMEOUT (Optional)	This is the amount of time allowed between job submit time in the queue and job processing (query processing) time. Default time in queue - 120 seconds
QUERY_DATA_QUERY_EXECUTION_TIMEOUT (Optional)	The amount of time allowed for query execution. Default execution time - 30 seconds
WORKSPACE_RESULT_LIMIT (Optional)	The number of workspaces that will be returned in the response by the get_workspaces tool. Default size of the workspaces list - 20
VIEW_RESULT_LIMIT (Optional)	The number of view that will be returned in the response by get_views tool. Default size of the views list - 30

3. Remote MCP Server Setup (Self-Hosted)

Remote MCP lets you host Zoho Analytics MCP once and share it with your organization over HTTP(S), removing local Docker installs, manual OAuth steps, and per-user updates. Authentication, token lifecycle, and upgrades are handled centrally so end users just point their MCP client to a single URL.

Client configuration

Any MCP host that supports the HTTP transport can point to your hosted instance:

{
  "mcpServers": {
    "ZohoAnalyticsMCP": {
      "url": "<hosted-mcp-server-url>",
      "type": "http"
    }
  }
}

or simply add the in the corresponding location the MCP host requires. Check the documentation of your MCP host for more details.

Self-hosting Setup Instructions

1. Register a static OAuth client in the Zoho Developer Console (server-based application). Set the redirect URI to <your-public-url>/auth/callback and record the client ID/secret.
2. Create a .env file for the hosted server with the variables below:

Variable	Description
ANALYTICS_SERVER_URL	Zoho Analytics API base URL (e.g., https://analyticsapi.zoho.in)
OIDC_PROVIDER_CLIENT_ID	Client ID from the OAuth app
OIDC_PROVIDER_CLIENT_SECRET	Client secret from the OAuth app
MCP_SERVER_PUBLIC_URL	Public HTTPS URL where your Remote MCP server is reachable
SESSION_SECRET_KEY	Random string used for session management
PORT (optional)	Override the default server port (4000)
MCP_SERVER_ORG_IDS	Comma-separated list of Zoho Analytics org IDs whose users are allowed to use the Remote MCP server
STORAGE_BACKEND	"memory" (default) or "redis" for distributed storage
REDIS_HOST/REDIS_PORT/REDIS_PASSWORD	Required only when STORAGE_BACKEND=redis

Before configuring and running the Remote MCP server, please check the Security Guidelines for best practices on securing your hosted instance.

3. Run the Remote MCP container on the host machine:

docker run --name remote-mcp-server \
    --network=host \
    --env-file .env \
    zohoanalytics/mcp-server:remote-v1.1

Once the container is running, share MCP_SERVER_PUBLIC_URL with your users; their MCP clients will connect over HTTP without any local setup.

4. Integrate with MCP Hosts

Zoho Analytics MCP Server can be integrated with any MCP host. Below are some sample integrations that demonstrate how this can be done.

Claude Desktop Configuration

To configure the Zoho Analytics MCP server with Claude Desktop, add the following configuration to your Claude settings:

1. Install Claude Desktop in your system.
2. Open the Claude Desktop application and navigate to Settings > Developer tab.
3. Click Edit Config to configure (claude_desktop_config.json) with your MCP server details.

{
  "mcpServers": {
    "ZohoAnalyticsMCP": {
      "command": "docker",
      "args": [
        "run",
        "-e", "ANALYTICS_CLIENT_ID=<YOUR_ANALYTICS_CLIENT_ID>",
        "-e", "ANALYTICS_CLIENT_SECRET=<YOUR_ANALYTICS_CLIENT_SECRET>",
        "-e", "ANALYTICS_REFRESH_TOKEN=<YOUR_ANALYTICS_REFRESH_TOKEN>",
        "-e", "ANALYTICS_ORG_ID=<YOUR_ANALYTICS_ORG_ID>",
        "-e", "ANALYTICS_MCP_DATA_DIR=<YOUR_ANALYTICS_MCP_DATA_DIR>",
        "--network=host",
        "-i",
        "--rm",
        "-v", "<YOUR_ANALYTICS_MCP_DATA_DIR>:<YOUR_ANALYTICS_MCP_DATA_DIR>",
        "zohoanalytics/mcp-server"
      ]
    }
  }
}

VSCode Configuration

To configure the Zoho Analytics MCP server with Visual Studio Code:

1. Install the VSCode in your system.
2. Open the VSCode application and navigate to Settings.
3. In the Settings page, search for MCP configurations. Select the Edit in settings.json option to configure the MCP server.

{
  "servers": {
    "zoho_analytics_mcp_server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-e", "ANALYTICS_CLIENT_ID=<YOUR_ANALYTICS_CLIENT_ID>",
        "-e", "ANALYTICS_CLIENT_SECRET=<YOUR_ANALYTICS_CLIENT_SECRET>",
        "-e", "ANALYTICS_REFRESH_TOKEN=<YOUR_ANALYTICS_REFRESH_TOKEN>",
        "-e", "ANALYTICS_ORG_ID=<YOUR_ANALYTICS_ORG_ID>",
        "-e", "ANALYTICS_MCP_DATA_DIR=<YOUR_LOCAL_DATA_DIR>",
        "--network=host",
        "-i",
        "--rm",
        "-v", "<YOUR_LOCAL_DATA_DIR>:<YOUR_LOCAL_DATA_DIR>",
        "zohoanalytics/mcp-server"
      ]
    }
  }
}

Cursor Configuration

To configure the Zoho Analytics MCP server with Cursor:

1. Install the Cursor in your system.
2. Open the Cursor application and navigate to Settings > Tools and Integrations.
3. Click the Add Custom MCP menu to enter your server configuration details, and Save.

{
  "mcpServers": {
    "ZohoAnalyticsMCP": {
      "command": "docker",
      "args": [
        "run",
        "-e", "ANALYTICS_CLIENT_ID=<YOUR_ANALYTICS_CLIENT_ID>",
        "-e", "ANALYTICS_CLIENT_SECRET=<YOUR_ANALYTICS_CLIENT_SECRET>",
        "-e", "ANALYTICS_REFRESH_TOKEN=<YOUR_ANALYTICS_REFRESH_TOKEN>",
        "-e", "ANALYTICS_ORG_ID=<YOUR_ANALYTICS_ORG_ID>",
        "-e", "ANALYTICS_MCP_DATA_DIR=<YOUR_ANALYTICS_MCP_DATA_DIR>",
        "--network=host",
        "-i",
        "--rm",
        "-v", "<YOUR_ANALYTICS_MCP_DATA_DIR>:<YOUR_ANALYTICS_MCP_DATA_DIR>",
        "zohoanalytics/mcp-server"
      ]
    }
  }
}

Tools List

The Zoho Analytics MCP server provides various tools for interacting with Zoho Analytics.

Tool	API Used	Description
create_workspace	Create Workspace	Creates a new workspace in Zoho Analytics with the given name.
create_table	Create Table	Creates a new table in a specified workspace with defined columns.
get_workspaces_list	Get All Workspaces	Fetches the list of workspaces in the user's organization.
search_views	search Views	Fetches the list of views (tables, reports, dashboards) within a specified workspace based on the query
get_view_details	Get View Details	Fetches the details of a specific view, including its structure and properties.
import_data	Import data - New table	Imports data into a specified table from a file or a list of dictionaries.
export_view	Export Data Export Data (Asynchronous) - For exporting Dashboards	Exports an object (table, chart, or dashboard) from the workspace in the specified format.
query_data	Create Export Job - Using SQL Query	Executes a SQL query on the specified workspace and returns the results.
create_aggregate_formula	Add Aggregate Formula	Creates an aggregate formula in a specified table that returns a single aggregate value.
create_query_table	Create Query Table	Creates a query table based on a SQL query for derived data views.
create_chart_report	Create Report	Creates a chart report (bar, line, pie, scatter, bubble) in the specified workspace.
create_pivot_report	Create Report	Creates a pivot table report for multidimensional data analysis.
create_summary_report	Create Report	Creates a summary report that groups data by specified columns and applies aggregate functions.
add_row	Add row	Adds a new row to a specified table.
update_rows	Update row	Updates rows in a specified table based on given criteria.
delete_rows	Delete row	Deletes rows from a specified table based on given criteria.
delete_view	Delete View	Deletes a view (table, report, or dashboard) from a workspace.
analyse_file_structure	Not Applicable	Analyzes the structure of a CSV or JSON file to determine its columns and data types.
download_file	Not Applicable	Downloads a file from a given URL and saves it to a local directory.

Troubleshooting

For common issues:

1. Authentication Problems:
   • Verify all OAuth credentials
   • Ensure tokens have proper permissions
   • Check token expiration status
2. Connection Issues:
   • Confirm if the Docker container is running
   • Validate network connectivity
   • Check firewall settings
3. Data Center Errors:
   • Verify ANALYTICS_SERVER_URL and ACCOUNTS_SERVER_URL matches your organization's region
   • Ensure the location code is correct (case-sensitive)
4. File System Problems:
   • Confirm if the data directory exists
   • Check directory permissions
   • Verify sufficient disk space