🚀 Empowering LLMs with Qlik Cloud: A Deep Dive into the Qlik MCP Server 📊

This document provides a comprehensive guide to the Qlik MCP Server, a crucial component for integrating Large Language Models (LLMs) with the Qlik Cloud API. This integration unlocks the power of Qlik's data analytics capabilities within LLM applications, enabling them to extract data from visualizations, understand data relationships, and generate insightful narratives.

🛠️ Toolset: Bridging the Gap Between LLMs and Qlik Cloud

The Qlik MCP Server exposes a suite of tools designed to facilitate seamless interaction between LLMs and Qlik Cloud. These tools empower LLMs to explore, understand, and extract valuable insights from Qlik applications.

qlik_get_apps: Unveiling the Qlik Application Landscape
- Functionality: This tool provides a comprehensive listing of all Qlik applications accessible within the workspace.
- Inputs:
  - limit (number, default: 100): Controls the maximum number of applications returned, allowing for efficient pagination.
  - offset (string): Enables pagination, allowing you to retrieve applications in batches.
- Output: A structured list of applications, each containing its unique ID and associated metadata.
qlik_get_app_sheets: Navigating the Structure of a Qlik Application
- Functionality: This tool retrieves a list of all sheets within a specified Qlik application, providing a roadmap to the application's structure.
- Inputs:
  - app_id (string): The unique identifier of the Qlik application. Defaults to the QLIK_APP_ID environment variable for convenience.
- Output: A detailed list of sheets, including their IDs, titles, and relevant metadata.
qlik_get_sheet_charts: Pinpointing Visualizations within a Sheet
- Functionality: This tool identifies all charts present within a specific sheet, enabling LLMs to target specific visualizations for data extraction.
- Inputs:
  - sheet_id (string): The unique identifier of the sheet containing the desired charts.
  - app_id (string, optional): The ID of the Qlik application (defaults to QLIK_APP_ID env variable).
- Output: A list of charts, including their IDs, types, and positional information within the sheet.
qlik_get_chart_data: Extracting Data from Qlik Visualizations
- Functionality: This tool is the core of the integration, allowing LLMs to extract the underlying data from a specific chart.
- Inputs:
  - sheet_id (string): The ID of the sheet containing the chart.
  - chart_id (string): The ID of the chart from which to extract data.
  - app_id (string, optional): The ID of the Qlik application (defaults to QLIK_APP_ID env variable).
  - max_rows (number, default: 10000): Limits the total number of rows retrieved, preventing excessive data transfer.
  - page_size (number, default: 1000): Controls the number of rows retrieved per request, optimizing performance.
  - include_metadata (boolean, default: true): Determines whether chart metadata is included in the response, providing valuable context.
- Output: A comprehensive dataset containing chart headers, rows, and optional metadata, ready for analysis by the LLM.

⚙️ Configuration: Setting Up the Qlik MCP Server

Proper configuration is essential for a secure and efficient integration. Follow these steps to set up the Qlik MCP Server:

Qlik Cloud API Key Generation:
- Log in to your Qlik Cloud tenant.
- Navigate to Settings > API keys.
- Create a new API key, ensuring it has the necessary permissions to access the desired Qlik applications and data. Important: Store the API key securely, as it grants access to your Qlik Cloud environment.
Environment Configuration:
- Create a .env file in the root directory of the Qlik MCP Server project.
- Populate the .env file with your Qlik Cloud credentials and configuration parameters, using the .env.example file as a template:
```
QLIK_API_KEY=your_api_key_here
QLIK_BASE_URL=your_tenant_url
QLIK_APP_ID=your_default_app_id
MAX_ROWS_PER_REQUEST=1000
MAX_TOTAL_ROWS=10000
REQUEST_DELAY_MS=100
MAX_RETRIES=3
RETRY_DELAY_MS=1000
```
  - QLIK_API_KEY: Your Qlik Cloud API key.
  - QLIK_BASE_URL: The base URL of your Qlik Cloud tenant.
  - QLIK_APP_ID: The default Qlik application ID to use when not explicitly specified.
  - MAX_ROWS_PER_REQUEST: The maximum number of rows to retrieve in a single request.
  - MAX_TOTAL_ROWS: The maximum total number of rows to retrieve for a chart.
  - REQUEST_DELAY_MS: A delay (in milliseconds) between requests to avoid rate limiting.
  - MAX_RETRIES: The maximum number of times to retry a failed request.
  - RETRY_DELAY_MS: The delay (in milliseconds) between retries.

🐳 Deployment: Running the Qlik MCP Server

The Qlik MCP Server can be deployed using Docker for a streamlined and consistent experience.

Build the Docker Image:
```
docker build -t qlik-mcp .
```
Run the Docker Container:
```
docker run --env-file .env qlik-mcp
```
Ensure that the .env file is properly configured before running the container.

🔌 Integration: Connecting to LLM Platforms

The Qlik MCP Server can be integrated with various LLM platforms, including Claude Desktop and Cursor.

Claude Desktop Configuration

Add the following configuration to your claude_desktop_config.json file:

Using Deno (Recommended)

{
  "mcpServers": {
    "qlik": {
      "command": "/path/to/deno",
      "args": ["run", "--allow-all", "--env-file=.env", "src/index.ts"],
      "cwd": "/path/to/qlik-mcp"
    }
  }
}

Using Node.js

{
  "mcpServers": {
    "qlik": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "env": {
        "QLIK_API_KEY": "your_api_key_here",
        "QLIK_BASE_URL": "your_tenant_url",
        "QLIK_APP_ID": "your_default_app_id"
      },
      "cwd": "/path/to/qlik-mcp"
    }
  }
}

Cursor Configuration

Open Cursor settings.
Navigate to the Claude configuration section.
Add a new MCP configuration:
```
{
  "name": "Qlik Cloud",
  "command": "/path/to/deno",
  "args": ["run", "--allow-all", "--env-file=.env", "src/index.ts"],
  "cwd": "/path/to/qlik-mcp"
}
```
Replace /path/to/deno with the actual path to your Deno installation (e.g., ~/.deno/bin/deno) and /path/to/qlik-mcp with the absolute path to your cloned repository.

🐛 Troubleshooting: Resolving Common Issues

401 Unauthorized: Verify that your API key is correct and active.
403 Forbidden: Ensure that the API key has the necessary permissions to access the requested Qlik applications and data.
429 Too Many Requests: Adjust the rate limiting settings (REQUEST_DELAY_MS, MAX_RETRIES, RETRY_DELAY_MS) in your .env file to align with Qlik Cloud's rate limits.
404 Not Found: Double-check the app, sheet, and chart IDs to ensure they are valid and exist in your Qlik Cloud environment.

🛠️ Development: Contributing to the Project

Prerequisites

Deno
Node.js (optional, for IDE support)

Local Setup

# Clone repository
git clone https://github.com/jwaxman19/qlik-mcp.git
cd qlik-mcp

# Install dependencies (for IDE support)
npm install

# Run server
deno task dev

By following this comprehensive guide, you can effectively leverage the Qlik MCP Server to integrate Qlik Cloud with your LLM applications, unlocking a wealth of data-driven insights and enhancing the capabilities of your AI-powered solutions.