Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/zoho/analytics-mcp-server


https://github.com/zoho/analytics-mcp-server

Last synced: about 1 month ago
JSON representation

Awesome Lists containing this project

README 

          
# 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](#1-docker-image-setup)

2. [Configuring Environment Variables](#2-configuring-environment-variables)

3. [Remote MCP Server Setup (Hosted Option)](#3-remote-mcp-server-setup-hosted-option)

4. [Integrating with MCP Hosts](#4-integrate-with-mcp-hosts)

    - [Claude Desktop](#claude-desktop-configuration)

    - [VSCode](#vscode-configuration)

    - [Cursor](#cursor-configuration)



### 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:



```bash

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](https://api-console.zoho.com/)

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](https://www.zoho.com/analytics/api/v2/authentication.html).



**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:



```json

{

  "mcpServers": {

    "ZohoAnalyticsMCP": {

      "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](https://api-console.zoho.com/) (server-based application). Set the redirect URI to `/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`](./SECURITY.md) for best practices on securing your hosted instance.



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



```bash

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](https://claude.ai/download) 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.



```json

{

  "mcpServers": {

    "ZohoAnalyticsMCP": {

      "command": "docker",

      "args": [

        "run",

        "-e", "ANALYTICS_CLIENT_ID=",

        "-e", "ANALYTICS_CLIENT_SECRET=",

        "-e", "ANALYTICS_REFRESH_TOKEN=",

        "-e", "ANALYTICS_ORG_ID=",

        "-e", "ANALYTICS_MCP_DATA_DIR=",

        "--network=host",

        "-i",

        "--rm",

        "-v", ":",

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



```json

{

  "servers": {

    "zoho_analytics_mcp_server": {

      "type": "stdio",

      "command": "docker",

      "args": [

        "run",

        "-e", "ANALYTICS_CLIENT_ID=",

        "-e", "ANALYTICS_CLIENT_SECRET=",

        "-e", "ANALYTICS_REFRESH_TOKEN=",

        "-e", "ANALYTICS_ORG_ID=",

        "-e", "ANALYTICS_MCP_DATA_DIR=",

        "--network=host",

        "-i",

        "--rm",

        "-v", ":",

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



```json

{

  "mcpServers": {

    "ZohoAnalyticsMCP": {

      "command": "docker",

      "args": [

        "run",

        "-e", "ANALYTICS_CLIENT_ID=",

        "-e", "ANALYTICS_CLIENT_SECRET=",

        "-e", "ANALYTICS_REFRESH_TOKEN=",

        "-e", "ANALYTICS_ORG_ID=",

        "-e", "ANALYTICS_MCP_DATA_DIR=",

        "--network=host",

        "-i",

        "--rm",

        "-v", ":",

        "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