# Qlik MCP Server

A Model Context Protocol (MCP) server that connects AI assistants like Claude, ChatGPT, and other LLMs to your Qlik Cloud and Qlik Sense Enterprise environments. Supports both stdio (Claude Desktop) and Streamable HTTP (ChatGPT) transports with optional Azure OpenAI / OpenAI LLM backends.

**Own your AI. Create your own way to interact with your data.**

## Features

- **59 MCP Tools** (Cloud) / **9 tools** (On-Premise)
- **Multi-Client Support** - Claude Desktop (stdio), ChatGPT (HTTP transport), VS Code
- **Dual Platform Support** - Qlik Cloud and Qlik Sense Enterprise (On-Premise)
- **Multi-LLM Backend** - Claude (Anthropic), Azure OpenAI, OpenAI
- **Natural Language Analytics** - Ask questions about your data in plain English
- **Full Lifecycle Management** - Apps, reloads, users, spaces, sheets, bookmarks
- **AI/ML Integration** - AutoML experiments, Qlik Answers assistants
- **Business Glossary & Data Products** - Glossary management, dataset stewardship
- **Enterprise Governance** - Users, roles, permissions, compliance

---

## Quick Start

### Prerequisites

- **Node.js 18+** - Download from [nodejs.org](https://nodejs.org/)
- **Claude Desktop** - Download from [claude.ai/download](https://claude.ai/download)
- **Qlik Cloud tenant** OR **Qlik Sense Enterprise server**

---

### Step 1: Download the MCP Server

#### Windows (Recommended)

1. **Download the ZIP file** from GitHub:
   - Go to: https://github.com/undsoul/qlik-claude-mcp
   - Click green **"Code"** button → **"Download ZIP"**

2. **Extract to C:\** (recommended for simple paths):
   - Right-click the downloaded ZIP → **Extract All**
   - Extract to: `C:\`
   - You should now have: `C:\qlik-claude-mcp-main\`

3. **Open PowerShell** and install dependencies:
   ```powershell
   cd C:\qlik-claude-mcp-main
   npm install
   ```

#### macOS / Linux

```bash
git clone https://github.com/undsoul/qlik-claude-mcp.git
cd qlik-claude-mcp
npm install
```

---

### Step 2: Install Claude Desktop

1. Download Claude Desktop from [claude.ai/download](https://claude.ai/download)
2. Install and sign in with your Anthropic account

---

### Step 3: Get Your Qlik API Key

#### For Qlik Cloud:
1. Log in to your Qlik Cloud tenant
2. Click your **profile icon** (top right) → **Profile settings**
3. Go to **API keys** section
4. Click **Generate new key**
5. Copy and save the API key (you won't see it again!)

#### For Qlik Sense Enterprise (On-Premise):

1. Open **QMC** → **Start** → **Certificates**
2. Add a machine name (e.g., `MCP-Client`)
3. Click **Export certificates**
4. **Important settings:**
   - **Certificate file format:** Choose **PEM format** (not Windows format)
   - Check **Include secret key**
5. Export and save the files:
   - `client.pem` - Client certificate
   - `client_key.pem` - Private key
6. Note the paths where you saved these files

---

### Step 4: Configure Claude Desktop

#### Open Config File (Easiest Way)

1. **Open Claude Desktop**
2. Click **Settings** (gear icon) or **File menu**
3. Click **"Edit Config"** or **"Settings" → "Developer" → "Edit Config"**
4. This opens `claude_desktop_config.json` in your default text editor
5. Paste the configuration below and **Save** (Ctrl+S)

> **Config file location:**
> - Windows: `C:\Users\{YourName}\AppData\Roaming\Claude\claude_desktop_config.json`
> - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

---

#### Qlik Cloud Examples

**Windows:**
```json
{
  "mcpServers": {
    "qlik-mcp-os": {
      "command": "node",
      "args": ["C:/qlik-claude-mcp-main/dist/index.js"],
      "env": {
        "QLIK_TENANT_URL": "https://your-tenant.eu.qlikcloud.com",
        "QLIK_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**macOS:**
```json
{
  "mcpServers": {
    "qlik-mcp-os": {
      "command": "node",
      "args": ["/Users/yourname/qlik-claude-mcp/dist/index.js"],
      "env": {
        "QLIK_TENANT_URL": "https://your-tenant.us.qlikcloud.com",
        "QLIK_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

---

#### Qlik Sense Enterprise (On-Premise) Examples

**Step 1: Export Certificates from QMC**

1. Open Qlik Management Console (QMC)
2. Go to **Certificates** under Configure System
3. Click **Export certificates**
4. Enter machine name (e.g., your server hostname)
5. Check **Include secret key**
6. Export format: **Platform independent PEM-format**
7. Click **Export** - saves to: `C:\ProgramData\Qlik\Sense\Repository\Exported Certificates\<machinename>\`

The folder will contain:
- `client.pem` - Client certificate
- `client_key.pem` - Client private key
- `root.pem` - Root CA certificate

**Step 2: Configure Claude Desktop**

**Windows:**
```json
{
  "mcpServers": {
    "qlik-onprem": {
      "command": "node",
      "args": ["C:/qlik-claude-mcp-main/dist/index.js"],
      "env": {
        "QLIK_TENANT_URL": "https://qlik-server.company.com",
        "QLIK_DEPLOYMENT": "on-premise",
        "QLIK_CERT_PATH": "C:/ProgramData/Qlik/Sense/Repository/Exported Certificates/YourServer",
        "QLIK_USER_DIRECTORY": "COMPANY",
        "QLIK_USER_ID": "administrator"
      }
    }
  }
}
```

**macOS/Linux:**
```json
{
  "mcpServers": {
    "qlik-onprem": {
      "command": "node",
      "args": ["/Users/yourname/qlik-claude-mcp/dist/index.js"],
      "env": {
        "QLIK_TENANT_URL": "https://qlik-server.company.com",
        "QLIK_DEPLOYMENT": "on-premise",
        "QLIK_CERT_PATH": "/path/to/exported-certificates",
        "QLIK_USER_DIRECTORY": "DOMAIN",
        "QLIK_USER_ID": "administrator"
      }
    }
  }
}
```

> **Note:**
> - `QLIK_CERT_PATH` is the **folder** containing `client.pem`, `client_key.pem`, and `root.pem`
> - `QLIK_USER_DIRECTORY` and `QLIK_USER_ID` specify which user to act as (e.g., `DOMAIN\administrator`)
> - The user must have appropriate access rights in QMC

---

#### Multi-Tenant & Hybrid Configurations

You can configure **multiple MCP servers** in the same config file to connect to different Qlik environments simultaneously. This supports:

- **Multiple Qlik Cloud tenants** (e.g., Dev, Test, Prod)
- **Multiple On-Premise servers**
- **Hybrid setups** (Cloud + On-Premise together)

**Example: Two Cloud Tenants + One On-Premise:**
```json
{
  "mcpServers": {
    "qlik-cloud-dev": {
      "command": "node",
      "args": ["C:/qlik-claude-mcp-main/dist/index.js"],
      "env": {
        "QLIK_TENANT_URL": "https://dev-tenant.eu.qlikcloud.com",
        "QLIK_API_KEY": "dev-api-key-here"
      }
    },
    "qlik-cloud-prod": {
      "command": "node",
      "args": ["C:/qlik-claude-mcp-main/dist/index.js"],
      "env": {
        "QLIK_TENANT_URL": "https://prod-tenant.eu.qlikcloud.com",
        "QLIK_API_KEY": "prod-api-key-here"
      }
    },
    "qlik-onprem": {
      "command": "node",
      "args": ["C:/qlik-claude-mcp-main/dist/index.js"],
      "env": {
        "QLIK_TENANT_URL": "https://qlik-server.company.com",
        "QLIK_DEPLOYMENT": "on-premise",
        "QLIK_CERT_PATH": "C:/ProgramData/Qlik/Sense/Repository/Exported Certificates/MyServer",
        "QLIK_USER_DIRECTORY": "COMPANY",
        "QLIK_USER_ID": "administrator"
      }
    }
  }
}
```

Each server appears as a separate MCP connection in Claude Desktop. You can specify which environment to use when asking questions:
- *"Using qlik-cloud-dev, list all apps"*
- *"On qlik-onprem, trigger reload for Sales Dashboard"*

---

#### ChatGPT / HTTP Transport

To use with ChatGPT or other HTTP-based LLM clients, set `MCP_TRANSPORT` to `http` or `both`:

```json
{
  "mcpServers": {
    "qlik-mcp-http": {
      "command": "node",
      "args": ["C:/qlik-claude-mcp-main/dist/index.js"],
      "env": {
        "QLIK_TENANT_URL": "https://your-tenant.eu.qlikcloud.com",
        "QLIK_API_KEY": "your-api-key-here",
        "MCP_TRANSPORT": "http",
        "MCP_HTTP_PORT": "3000"
      }
    }
  }
}
```

The server exposes a Streamable HTTP endpoint at `http://localhost:3000/mcp` with:
- `POST /mcp` - JSON-RPC request/response
- `GET /mcp` - Server-Sent Events (SSE) streaming
- `DELETE /mcp` - Session cleanup
- `GET /health` - Health check

Use `MCP_TRANSPORT=both` to serve both stdio (Claude Desktop) and HTTP (ChatGPT) simultaneously.

---

### Step 5: Build the MCP Server

**After saving your config**, go back to PowerShell (Windows) or Terminal (macOS) and run:

#### Windows
```powershell
npm run build
```

#### macOS / Linux
```bash
npm run build
```

**Verify build succeeded** - you should see `dist/index.js` created.

---

### Step 6: Restart Claude Desktop

1. **Quit Claude Desktop completely** (not just close the window)
   - macOS: Right-click Claude in menu bar → Quit
   - Windows: Right-click Claude in system tray → Exit
2. **Reopen Claude Desktop**
3. Start a new conversation and try: *"Check my Qlik health"*

---

### Verify It's Working

In Claude Desktop, type:

```
Check my Qlik environment health
```

You should see Claude use the `qlik_health_check` tool and return your tenant status.

---

## Tool Capabilities (59 Tools)

### On-Premise Tools (9 tools — work on both Cloud & On-Premise)

| Tool | Description |
|------|-------------|
| `qlik_search` | Search apps, datasets, automations, and more |
| `qlik_health_check` | Check server status and connectivity |
| `qlik_app_details` | Get app metadata (name, owner, space, status) |
| `qlik_app_context` | Get full app structure (tables, fields, sheets, measures, bookmarks, variables) |
| `qlik_trigger_app_reload` | Trigger an app reload |
| `qlik_get_reload_status` | Check reload task status |
| `qlik_generate_app` | Create or update a Qlik app with script and data connections |
| `qlik_get_app_script` | Extract the full load script from an app |
| `qlik_insight_advisor` | Ask natural language questions about app data |

---

### Cloud-Only Tools (50 tools)

### 1. Governance (4) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_get_tenant_info` | Get tenant information |
| `qlik_search_users` | Search users by name or email |
| `qlik_get_user_info` | Get detailed user information |
| `qlik_get_license_info` | Get license and seat allocation |

---

### 2. Reload & History (2) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_cancel_reload` | Cancel a running reload |
| `qlik_get_reload_info` | Get reload history for an app |

---

### 3. Spaces & Catalog (2) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_get_spaces_catalog` | List all spaces |
| `qlik_space_details` | Get space contents with all items |

---

### 4. Lineage (2) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_get_lineage` | Get data lineage for a resource |
| `qlik_app_lineage` | Get app data sources and connection info |

---

### 5. Data & Selections (5) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_get_dataset_details` | Get dataset/data connection details |
| `qlik_apply_selections` | Apply field selections |
| `qlik_clear_selections` | Clear all selections |
| `qlik_get_current_selections` | Get active selections |
| `qlik_get_available_fields` | List all fields in an app |

---

### 6. Master Items (4) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_list_master_measures` | List master measures with expressions |
| `qlik_list_master_dimensions` | List master dimensions |
| `qlik_get_variables` | Get all variables with definitions |
| `qlik_set_variable` | Create or update a variable |

---

### 7. Field Values (1) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_get_field_values` | Get distinct values for a field |

---

### 8. Data Connections (2) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_get_data_sources` | Get data connection details for an app |
| `qlik_list_data_connections` | List tenant-level data connections |

---

### 9. Bookmarks & Stories (3) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_list_bookmarks` | List bookmarks with selections |
| `qlik_apply_bookmark` | Apply a saved bookmark |
| `qlik_list_stories` | List data stories |

---

### 10. App Generation (1)

| Tool | Description | Platforms |
|------|-------------|-----------|
| `qlik_generate_app` | Create or update a Qlik app with script and data connections | Both |

#### Cloud Workflow

On Qlik Cloud, `qlik_generate_app` uses REST APIs to create apps and trigger reloads asynchronously.

**Cloud Example Prompts:**

| What you say | What happens |
|--------------|--------------|
| "Create a Qlik app with sample sales data" | Creates app with inline LOAD script |
| "Create a new app called 'Dashboard' and load this data..." | Creates app in personal space |
| "Update the load script for app abc-123" | Updates existing app's script |

**Typical Cloud Workflow:**

1. **Create app with inline data:**
   ```
   "Create a Qlik app called 'Sales Analysis' with sample data
   for products, regions, and sales amounts"
   ```

2. **Create app using existing dataset:**
   ```
   "Create a Qlik app that loads from the 'Sales.qvd' dataset
   in my Data space"
   ```

3. **Update existing app:**
   ```
   "Update app abc-123 with a new load script that adds
   a calculated field for profit margin"
   ```

**Cloud Data Connection Note:**
On Cloud, data connections are managed via the Qlik Cloud hub or Spaces. Use `qlik_search` with `types: ["dataconnection"]` to find existing connections, then reference them in your load script using `LIB CONNECT TO`.

---

#### On-Premise Workflow (Engine API)
On Qlik Sense Enterprise, the tool uses the Engine API via WebSocket (port 4747) with certificate authentication:

1. **Create App** - `Global.CreateApp()`
2. **Create Data Connection** (optional) - `Doc.CreateConnection()`
3. **Set Load Script** - `Doc.SetScript()`
4. **Execute Reload** - `Doc.DoReload()`
5. **Save App** - `Doc.DoSave()`

**On-Premise Example Prompts:**

| What you say | What happens |
|--------------|--------------|
| "List available ODBC data sources on the server" | Lists all DSNs configured on the Qlik server |
| "Show me the data connections in app abc-123" | Lists all connections in the specified app |
| "Create a Qlik app with sample sales data" | Creates app with inline LOAD script |
| "Create an app that loads data from C:\Data\sales.csv" | Creates folder connection + app |
| "Create an app connected to SQL Server DSN 'MySQLServer'" | Creates ODBC connection + app |

**Typical On-Premise Workflow:**

1. **Discover data sources:**
   ```
   "What ODBC data sources are available on the Qlik server?"
   ```

2. **Explore existing app connections:**
   ```
   "List the data connections in the Sales Dashboard app"
   ```

3. **Create app with data:**
   ```
   "Create a new Qlik app called 'Customer Analysis' that connects to
   the folder C:\QlikData and loads customers.csv"
   ```

**Discovery Parameters:**
```json
// List available ODBC data sources on the server
{ "listOdbcDsns": true }

// List connections in an existing app
{ "appId": "abc-123", "listConnections": true }
```

**On-Premise Data Connection Examples:**

*Folder Connection:*
```json
{
  "appName": "SalesReport",
  "dataConnection": {
    "connectionName": "SalesData",
    "connectionType": "folder",
    "connectionString": "C:\\Data\\Sales\\"
  },
  "loadScript": "LOAD * FROM [lib://SalesData/sales.csv] (txt, codepage is 1252, embedded labels, delimiter is ',', msq);"
}
```

*ODBC Connection:*
```json
{
  "appName": "SQLReport",
  "dataConnection": {
    "connectionName": "SQLServer",
    "connectionType": "ODBC",
    "connectionString": "DSN=MyDSN",
    "username": "user",
    "password": "pass"
  },
  "loadScript": "LIB CONNECT TO 'SQLServer';\nSQL SELECT * FROM Sales;"
}
```

> **Note:** On-premise uses Engine API (port 4747) with certificate auth. Ensure certificates are properly exported from QMC.

---

### 11. Sheets & Visualization (2) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_list_sheets` | List all sheets in an app |
| `qlik_get_sheet_details` | Get sheet objects and chart details |

---

### 12. Automation (4) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_automation_list` | List all automations |
| `qlik_automation_get_details` | Get automation details |
| `qlik_automation_run` | Execute an automation |
| `qlik_automation_list_runs` | List automation runs |

---

### 13. Alerts (4) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_alert_list` | List all data alerts |
| `qlik_alert_get` | Get alert details |
| `qlik_alert_trigger` | Manually trigger an alert |
| `qlik_alert_delete` | Delete an alert |

---

### 14. Qlik Answers (3) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_answers_list_assistants` | List AI assistants |
| `qlik_answers_get_assistant` | Get assistant details |
| `qlik_answers_ask_question` | Ask a question to an assistant |

---

### 15. AutoML (4) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_automl_get_experiments` | List ML experiments |
| `qlik_automl_get_experiment` | Get experiment details |
| `qlik_automl_list_deployments` | List ML deployments |
| `qlik_automl_get_deployment` | Get deployment details |

---

### 16. Business Glossary (5) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_glossary_list` | List business glossaries |
| `qlik_glossary_details` | Get glossary details |
| `qlik_glossary_get_term` | Get term details |
| `qlik_glossary_create_term` | Create a new term |
| `qlik_glossary_delete_term` | Delete a term |

---

### 17. Datasets & Data Products (3) - Cloud Only

| Tool | Description |
|------|-------------|
| `qlik_get_dataset_profile` | Get dataset profiling stats |
| `qlik_list_data_products` | List data products |
| `qlik_get_data_product` | Get data product details |

---

## Usage Examples

### Basic Queries

```
You: "Check the health of my Qlik Cloud tenant"
Claude: [Uses qlik_health_check] Your tenant is healthy...

You: "List all spaces"
Claude: [Uses qlik_get_spaces_catalog] Found 57 spaces...

You: "Search for users named John"
Claude: [Uses qlik_search_users] Found 3 users matching 'John'...
```

### App Analysis

```
You: "Show me the details of my Sales Dashboard app"
Claude: [Uses qlik_app_details] App: Sales Dashboard, Owner: admin...

You: "Get the full context of the app - tables, fields, measures"
Claude: [Uses qlik_app_context] The app has 5 tables, 45 fields,
       12 master measures, 8 master dimensions...

You: "Select USA in the Country field, then show me the current selections"
Claude: [Uses qlik_apply_selections, qlik_get_current_selections]
       Selection applied. Current selections: Country = USA
```

### Reload Management

```
You: "Reload the Finance Dashboard"
Claude: [Uses qlik_trigger_app_reload] Reload started. Task ID: xyz...

You: "Check the reload status"
Claude: [Uses qlik_get_reload_status] Reload completed successfully...

You: "Get reload history for that app"
Claude: [Uses qlik_get_reload_info] Last 5 reloads shown...
```

### AI/ML Features

```
You: "List all Qlik Answers assistants"
Claude: [Uses qlik_answers_list_assistants] Found 3 assistants...

You: "Ask the Sales Assistant: What were our top products last quarter?"
Claude: [Uses qlik_answers_ask_question] Based on the data,
       your top 5 products were...

You: "List AutoML experiments"
Claude: [Uses qlik_automl_get_experiments] Found 2 experiments...
```

---

## Platform Support

### Qlik Cloud
All **59 tools** are available on Qlik Cloud.

### Qlik Sense Enterprise (On-Premise)
**9 tools** work on-premise: search, health check, app details, app context, reload, generate app, get script, and insight advisor.

Cloud-only features return informative messages:

```json
{
  "success": false,
  "error": "This feature is only available on Qlik Cloud",
  "platform": "on-premise",
  "suggestion": "Alternative approach for on-premise..."
}
```

#### Cloud-Only Features (50 tools)
- Governance (4 tools)
- Reload & History (2 tools)
- Spaces & Catalog (2 tools)
- Lineage (2 tools)
- Data & Selections (5 tools)
- Master Items (4 tools)
- Field Values (1 tool)
- Data Connections (2 tools)
- Bookmarks & Stories (3 tools)
- Sheets & Visualization (2 tools)
- Automation (4 tools)
- Data Alerts (4 tools)
- Qlik Answers (3 tools)
- AutoML (4 tools)
- Business Glossary (5 tools)
- Datasets & Data Products (3 tools)

#### On-Premise Equivalents
| Cloud Feature | On-Premise Alternative |
|---------------|----------------------|
| Spaces | Streams (via QRS `/qrs/stream`) |
| Items API | QRS App API (`/qrs/app`) |
| Cloud Reloads | QRS Reload Tasks (`/qrs/reloadtask`) |
| Insight Advisor | NL Query API (`/api/v1/nl/query`) |
| App Create/Script | Engine API (`Global.CreateApp`, `Doc.SetScript`, `Doc.DoReload`) |
| Data Connections | Engine API (`Doc.CreateConnection`, `Doc.GetConnections`) |
| ODBC Discovery | Engine API (`Global.GetOdbcDsns`) |

---

## Testing

### Quick Smoke Test

```bash
export QLIK_TENANT_URL=https://your-tenant.qlikcloud.com
export QLIK_API_KEY=your-api-key
node test-cloud-quick.cjs
```

### Full Handler Test

```bash
node test-mcp-handlers.mjs
```

---

## Environment Variables

### Core Settings

| Variable | Required | Description |
|----------|----------|-------------|
| `QLIK_TENANT_URL` | Yes | Qlik Cloud URL or Qlik Sense Enterprise server URL |
| `QLIK_DEPLOYMENT` | No | `cloud` (default) or `on-premise` |

**For Qlik Cloud:**

| Variable | Required | Description |
|----------|----------|-------------|
| `QLIK_API_KEY` | Yes | API key from Qlik Cloud hub |

**For Qlik Sense Enterprise (On-Premise):**

| Variable | Required | Description |
|----------|----------|-------------|
| `QLIK_CERT_PATH` | Yes | **Folder** containing `client.pem`, `client_key.pem`, `root.pem` |
| `QLIK_USER_DIRECTORY` | Yes | Windows domain (e.g., `COMPANY`) |
| `QLIK_USER_ID` | Yes | Username to act as (e.g., `admin`) |
| `QLIK_VIRTUAL_PROXY` | No | Virtual proxy prefix (if configured) |

### Transport Settings (for ChatGPT / HTTP clients)

| Variable | Required | Description |
|----------|----------|-------------|
| `MCP_TRANSPORT` | No | Transport type: `stdio` (default), `http`, or `both` |
| `MCP_HTTP_PORT` | No | HTTP server port (default: `3000`) |
| `MCP_HTTP_HOST` | No | HTTP server host (default: `0.0.0.0`) |
| `MCP_ALLOWED_ORIGINS` | No | Comma-separated CORS origins |
| `MCP_RATE_LIMIT` | No | Requests per minute per session (default: `300`) |
| `MCP_SESSION_TIMEOUT` | No | Session timeout in seconds (default: `3600`) |

### LLM Provider Settings (optional)

| Variable | Required | Description |
|----------|----------|-------------|
| `LLM_PROVIDER` | No | LLM backend: `claude` (default), `azure-openai`, or `openai` |

**For Claude (Anthropic):**

| Variable | Required | Description |
|----------|----------|-------------|
| `CLAUDE_API_KEY` | No | Anthropic API key |
| `CLAUDE_MODEL` | No | Model name (default: `claude-sonnet-4-20250514`) |

**For Azure OpenAI:**

| Variable | Required | Description |
|----------|----------|-------------|
| `AZURE_OPENAI_ENDPOINT` | Yes* | Azure OpenAI endpoint URL |
| `AZURE_OPENAI_API_KEY` | Yes* | Azure OpenAI API key |
| `AZURE_OPENAI_DEPLOYMENT` | No | Deployment name (default: `gpt-4o`) |
| `AZURE_OPENAI_API_VERSION` | No | API version (default: `2024-10-21`) |

**For OpenAI:**

| Variable | Required | Description |
|----------|----------|-------------|
| `OPENAI_API_KEY` | Yes* | OpenAI API key |
| `OPENAI_MODEL` | No | Model name (default: `gpt-4o`) |

> *Required only when using that specific LLM provider

---

## Troubleshooting

### "Tool not found" Error
Ensure the MCP server is running and Claude Desktop was restarted after configuration.

### Authentication Errors

**Qlik Cloud:**
- Verify your API key is valid and not expired
- Ensure the API key has appropriate permissions

**Qlik Sense Enterprise (On-Premise):**
- Verify certificate paths are correct and files exist
- Ensure certificates were exported with the private key
- Check that the certificate hasn't expired
- Verify the machine name in the certificate matches your setup

### "Cloud-only feature" Message
Some tools are only available on Qlik Cloud. The error message will suggest alternatives.

### Connection Timeout
Check network connectivity to your Qlik server. Ensure firewalls allow the connection.

### Empty MCP Server / Tools Not Showing

If Claude Desktop shows empty MCP server with no tools:

1. **Check if dist/ folder exists:**
   ```powershell
   dir C:\qlik-claude-mcp-main\dist\
   ```
   If not, run `npm run build` first.

2. **Check MCP server logs:**
   ```powershell
   type "$env:APPDATA\Claude\logs\mcp-server-qlik-mcp-os.log"
   ```

3. **Fully restart Claude Desktop:**
   - Close Claude Desktop
   - Open Task Manager (Ctrl+Shift+Esc)
   - Find "Claude" and click **End Task**
   - Reopen Claude Desktop

4. **Verify config file location:**
   ```powershell
   type "$env:APPDATA\Claude\claude_desktop_config.json"
   ```

### Server Hangs or Slow Response

If the server hangs or responds slowly, use optimized config with memory settings:

```json
{
  "mcpServers": {
    "qlik-mcp-os": {
      "command": "node",
      "args": [
        "--max-old-space-size=4096",
        "C:\\qlik-claude-mcp-main\\dist\\index.js"
      ],
      "env": {
        "QLIK_TENANT_URL": "https://your-tenant.qlikcloud.com",
        "QLIK_API_KEY": "your-api-key",
        "NODE_ENV": "production"
      }
    }
  }
}
```

### "Cannot find module" Error

This means `npm run build` was not executed:

```powershell
cd C:\qlik-claude-mcp-main
npm install
npm run build
```

Then restart Claude Desktop.

---

## Architecture

```
┌─────────────────┐                          ┌─────────────────┐
│  Claude Desktop │──stdio──┐                │   Qlik Cloud    │
│                 │         │                │   (REST APIs)   │
└─────────────────┘         ▼                │                 │
                    ┌─────────────────┐      ├─────────────────┤
┌─────────────────┐ │   MCP Server    │─────▶│ Qlik Sense Ent. │
│  ChatGPT / Web  │ │                 │      │ (QRS + Engine)  │
│  LLM Clients    │ │  59 Tools       │◀─────└─────────────────┘
└────────┬────────┘ │  17 Categories  │
         │          └─────────────────┘
         └──HTTP────────────┘
```

**Transports:**
- **stdio** - Claude Desktop, VS Code (default)
- **Streamable HTTP** - ChatGPT, web-based clients (`POST/GET/DELETE /mcp`)

**Qlik Cloud:** REST APIs (`/api/v1/*`) with API key authentication

**Qlik Sense Enterprise (On-Premise):**
- QRS API (port 4242) - Management operations
- Engine API (port 4747) - App creation, scripts, data connections via WebSocket

**LLM Backends (optional):**
- Claude (Anthropic) | Azure OpenAI | OpenAI

---

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `npm test`
5. Submit a pull request

---

## License

MIT License - See LICENSE file for details.

---

## Support

- **Issues**: [GitHub Issues](https://github.com/undsoul/qlik-claude-mcp/issues)
- **Documentation**: See `/docs` folder
- **Qlik Community**: [community.qlik.com](https://community.qlik.com)

---

*Built with the Model Context Protocol (MCP) for seamless AI-analytics integration.*