arthurfantaci/qlik-mcp-server

# Clone the repository
git clone https://github.com/arthurfantaci/qlik-mcp-server.git
cd qlik-mcp-server

# Install with UV (strongly recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh  # Install UV if not already installed
uv sync  # Creates virtual environment and installs all dependencies automatically

# Copy the example environment file
cp .env.example .env

# Edit .env with your Qlik Sense server details
# See .env.example for detailed configuration instructions

certs/
├── root.pem          # Server root certificate
├── client.pem        # Client certificate  
└── client_key.pem    # Client private key

# Test basic Qlik connection
uv run pytest tests/test_qlik_connection.py -v

# Test application listing
uv run pytest tests/test_list_apps.py -v

# Run all unit tests (no Qlik server required)
uv run pytest -m unit

# Run integration tests (requires Qlik server)
uv run pytest -m integration

# For project-specific configuration (recommended)
mkdir -p .cursor
cp examples/cursor_config.json .cursor/mcp.json

# OR for global configuration
cp examples/cursor_config.json ~/.cursor/mcp.json

# Update the paths in the configuration to match your setup
# Enable MCP in Cursor Settings and restart Cursor

# Copy example configuration to VS Code settings
cp examples/vscode_config.json ~/.vscode/settings.json

# Or merge with existing VS Code settings
# Update the paths in the configuration to match your setup

# Copy example configuration to Claude Desktop
cp examples/claude_desktop_config.json ~/.config/claude_desktop_config.json

# Edit the configuration file to update paths
# Then restart Claude Desktop

# Using Python 3.11 (recommended)
/opt/homebrew/bin/python3.11 -m src.server

# Or using the startup script
/opt/homebrew/bin/python3.11 start_server.py

"Get the script from app 12345678-abcd-1234-efgh-123456789abc"

"Analyze the script from app 12345678-abcd-1234-efgh-123456789abc and show me all BINARY LOAD statements"

Parameters used:
- analyze_script: true
- Result includes: BINARY LOAD statements with source apps, variable declarations, statement counts

"Get the script from app 12345678-abcd-1234-efgh-123456789abc and break it down by sections"

Parameters used:
- include_sections: true  
- Result: Script organized by ///$tab sections with line ranges

"Show me the first 1000 characters of the script from app 12345678-abcd-1234-efgh-123456789abc with line numbers"

Parameters used:
- max_preview_length: 1000
- include_line_numbers: true
- Result: Truncated script with line numbers for easy reference

"Perform a comprehensive analysis of the script from app 12345678-abcd-1234-efgh-123456789abc including BINARY LOAD detection, sections, and show line numbers"

Parameters used:
- analyze_script: true
- include_sections: true  
- include_line_numbers: true
- Result: Full analysis with BINARY LOAD extraction, sections, variables, and formatted output

"Show me all available Qlik Sense applications"

"Get all measures from Qlik app 12345678-abcd-1234-efgh-123456789abc with expressions and tags"

"Show me all variables in the application including their definitions"

"Get all fields and table information to understand the data model structure"

"List all sheets in the application with their metadata"

"Get all visualization objects from sheet 'Overview' with their properties and layout"

"Show me all dimensions with their grouping and metadata information"

"Get the complete data loading script for this application"

"Show me all data sources and their lineage, including binary and file sources"

{
  "app_id": "12345678-abcd-1234-efgh-123456789abc",
  "measures": [
    {
      "id": "measure_id",
      "title": "Revenue",
      "description": "Total revenue calculation",
      "expression": "Sum(Sales)",
      "label": "Total Revenue",
      "tags": ["finance", "kpi"]
    }
  ],
  "count": 25,
  "retrieved_at": "2025-08-29T10:30:00Z",
  "options": {
    "include_expression": true,
    "include_tags": true
  }
}

{
  "applications": [
    {
      "app_id": "12345678-abcd-1234-efgh-123456789abc",
      "name": "CRM Dashboard",
      "last_reload_time": "2025-08-29T10:30:00Z",
      "meta": {},
      "doc_type": ""
    }
  ],
  "count": 50,
  "retrieved_at": "2025-08-29T10:30:00Z"
}

{
  "app_id": "12345678-abcd-1234-efgh-123456789abc",
  "variables": [
    {
      "name": "vDataSource",
      "definition": "dev",
      "tags": [],
      "is_reserved": false,
      "is_config": false
    }
  ],
  "count": 25,
  "retrieved_at": "2025-08-29T10:30:00Z",
  "options": {
    "include_definition": true,
    "include_tags": true,
    "show_reserved": true,
    "show_config": true
  }
}

{
  "app_id": "12345678-abcd-1234-efgh-123456789abc",
  "fields": [
    {
      "name": "customer_id",
      "source_tables": ["fact_crm", "dim_customer"],
      "is_system": false,
      "is_hidden": false,
      "is_numeric": true,
      "cardinal": 4818662,
      "tags": ["$key", "$numeric", "$integer"]
    }
  ],
  "tables": [
    "fact_transactions",
    "dim_customer_details"
  ],
  "field_count": 60,
  "table_count": 10,
  "retrieved_at": "2025-08-29T10:30:00Z",
  "options": {
    "show_system": true,
    "show_hidden": true,
    "show_derived_fields": true,
    "show_semantic": true,
    "show_src_tables": true,
    "show_implicit": true
  }
}

{
  "app_id": "12345678-abcd-1234-efgh-123456789abc",
  "sheets": [
    {
      "id": "sheet_abc123",
      "title": "Summary View",
      "description": "Summary of OKRs",
      "rank": 0,
      "columns": 14,
      "rows": 10,
      "meta": {
        "created": "2025-08-15T09:00:00Z",
        "modified": "2025-08-29T10:30:00Z",
        "published": true
      }
    }
  ],
  "count": 5,
  "retrieved_at": "2025-08-29T10:30:00Z",
  "options": {
    "include_thumbnail": false,
    "include_metadata": true
  }
}

{
  "app_id": "12345678-abcd-1234-efgh-123456789abc",
  "sheet_id": "sheet_abc123",
  "objects": [
    {
      "id": "object_xyz789",
      "type": "barchart",
      "title": "Sales by Region",
      "subtitle": "Last 12 months",
      "position": {
        "x": 0,
        "y": 0,
        "width": 12,
        "height": 6
      },
      "properties": {
        "dimensions": ["Region"],
        "measures": ["Sum(Sales)"],
        "color": {
          "auto": true
        }
      },
      "layout": {
        "visualization": "barchart",
        "version": "1.0"
      }
    }
  ],
  "count": 12,
  "retrieved_at": "2025-08-29T10:30:00Z",
  "options": {
    "include_properties": true,
    "include_layout": true,
    "include_data_definition": true,
    "resolve_master_items": true
  }
}

{
  "app_id": "12345678-abcd-1234-efgh-123456789abc",
  "dimensions": [
    {
      "id": "dim_product_category",
      "title": "Product Category",
      "description": "Product categorization hierarchy",
      "grouping": "N",
      "field_defs": ["Category"],
      "field_labels": ["Product Category"],
      "tags": ["product", "hierarchy"],
      "meta": {
        "created": "2025-08-10T14:30:00Z",
        "approved": true
      }
    }
  ],
  "count": 30,
  "retrieved_at": "2025-08-29T10:30:00Z",
  "options": {
    "include_title": true,
    "include_tags": true,
    "include_grouping": true,
    "include_info": true
  }
}

{
  "app_id": "12345678-abcd-1234-efgh-123456789abc",
  "script": "// Main data loading script\n\n// Load sales data\nSales:\nLOAD\n    OrderID,\n    CustomerID,\n    ProductID,\n    Quantity,\n    UnitPrice,\n    OrderDate\nFROM [lib://DataFiles/sales.qvd] (qvd);\n\n// Load customer data\nCustomers:\nLOAD\n    CustomerID,\n    CustomerName,\n    Region,\n    Country\nFROM [lib://DataFiles/customers.xlsx]\n(ooxml, embedded labels, table is Customers);\n",
  "script_length": 245,
  "retrieved_at": "2025-08-29T10:30:00Z"
}

{
  "app_id": "12345678-abcd-1234-efgh-123456789abc",
  "data_sources": [
    {
      "name": "sales.qvd",
      "type": "file",
      "connection_string": "lib://DataFiles/sales.qvd",
      "statement": "LOAD * FROM [lib://DataFiles/sales.qvd] (qvd);",
      "discrimination": {
        "type": "DataConnection",
        "label": "QVD file source"
      }
    },
    {
      "name": "CustomerAnalytics.qvf",
      "type": "binary",
      "connection_string": "lib://Apps/CustomerAnalytics.qvf",
      "statement": "binary [lib://Apps/CustomerAnalytics.qvf];",
      "discrimination": {
        "type": "BinaryLoad",
        "label": "Binary application load"
      }
    },
    {
      "name": "TempTable",
      "type": "resident",
      "connection_string": "Resident SalesData",
      "statement": "LOAD CustomerID, Sum(Amount) as TotalSales RESIDENT SalesData GROUP BY CustomerID;",
      "discrimination": {
        "type": "ResidentLoad",
        "label": "Resident table transformation"
      }
    }
  ],
  "source_counts": {
    "binary": 1,
    "file": 3,
    "resident": 8,
    "inline": 1,
    "other": 0
  },
  "total_sources": 13,
  "retrieved_at": "2025-08-29T10:30:00Z",
  "options": {
    "include_resident": true,
    "include_file": true,
    "include_binary": true,
    "include_inline": true
  }
}

qlik-mcp-server/
├── .github/workflows/      # CI/CD automation
│   └── test.yml           # GitHub Actions test pipeline
├── .claude/                # Claude Code configuration
│   └── settings.local.json # Local Claude settings
├── src/                    # Core application code
│   ├── __init__.py         # Package initialization
│   ├── server.py           # FastMCP server implementation
│   ├── qlik_client.py      # Qlik Engine API WebSocket client
│   └── tools.py            # MCP tool definitions and implementations
├── tests/                  # Comprehensive test suite (pytest)
│   ├── conftest.py         # Pytest configuration and fixtures
│   ├── README.md           # Testing documentation and guidelines
│   ├── test_qlik_connection.py    # Test basic connection
│   ├── test_list_apps.py          # Test application listing
│   ├── test_mcp_tool.py           # Test MCP tool functions (includes measures)
│   ├── test_variables.py          # Test variable retrieval
│   ├── test_fields.py             # Test field retrieval
│   ├── test_sheets.py             # Test sheet retrieval
│   ├── test_dimensions.py         # Test dimension retrieval
│   ├── test_script.py             # Test script retrieval and analysis
│   ├── test_data_sources.py       # Test data source retrieval
│   ├── test_binary_extraction.py  # Test BINARY LOAD extraction
│   ├── test_vizlib_container.py   # Test VizlibContainer functionality
│   └── test_both_tools.py         # Test multiple tools together
├── examples/               # Configuration examples
│   ├── cursor_config.json         # Cursor IDE configuration
│   ├── vscode_config.json         # VS Code configuration
│   ├── claude_desktop_config.json # Claude Desktop configuration
│   └── README.md           # Configuration instructions
├── docs/                   # Documentation
│   ├── CERTIFICATES.md     # Certificate setup guide
│   ├── API_REFERENCE.md    # Complete API documentation
│   ├── SCRIPT_TOOL_USAGE.md # Script tool usage guide
│   └── TROUBLESHOOTING.md  # Troubleshooting guide
├── certs/                  # SSL certificates (gitignored)
│   ├── root.pem           # Server root certificate
│   ├── client.pem         # Client certificate
│   └── client_key.pem     # Client private key
├── .env.example           # Example environment configuration
├── .env.test.example      # Test environment configuration template
├── .env                   # Environment configuration (gitignored)
├── .gitignore            # Git ignore rules
├── pyproject.toml         # Python project configuration and dependencies
├── pytest.ini            # Pytest configuration and markers
├── uv.lock               # UV dependency lockfile for reproducible builds
├── start_server.py       # Server startup script
├── CLAUDE.md             # Claude Code instructions
├── CONTRIBUTING.md       # Contribution guidelines
├── LICENSE               # MIT license
└── README.md             # This documentation

# Install test dependencies (automatically handled by UV)
uv sync  # Installs both main and dev dependencies including pytest

# Configure test environment for integration tests
cp .env.test.example .env.test
# Edit .env.test with your Qlik server details (when available)

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run only unit tests (no Qlik server required - perfect for development)
uv run pytest -m unit

# Run integration tests (requires Qlik server connection)
uv run pytest -m integration

# Run with coverage report
uv run pytest --cov=src --cov-report=html

# Run specific test file
uv run pytest tests/test_mcp_tool.py

# Run specific test function
uv run pytest tests/test_mcp_tool.py::test_get_app_measures_mock

# Test specific components with pytest
uv run pytest tests/test_mcp_tool.py -v           # MCP tool functions (includes measures)
uv run pytest tests/test_variables.py -v          # Variable retrieval
uv run pytest tests/test_fields.py -v             # Field and table information
uv run pytest tests/test_sheets.py -v             # Sheet metadata
uv run pytest tests/test_dimensions.py -v         # Dimension analysis
uv run pytest tests/test_script.py -v             # Script retrieval and analysis
uv run pytest tests/test_data_sources.py -v       # Data source lineage
uv run pytest tests/test_binary_extraction.py -v  # BINARY LOAD extraction
uv run pytest tests/test_vizlib_container.py -v   # VizlibContainer functionality
uv run pytest tests/test_both_tools.py -v         # Multiple tools together

# Debug Qlik client directly
uv run python -m src.qlik_client

# Run Ruff linting and formatting
uv run ruff check                    # Check for style and quality issues
uv run ruff check --fix              # Auto-fix issues where possible
uv run ruff format                   # Format code according to standards

# The project is configured with:
# - pyproject.toml: Ruff configuration for consistent code style
# - Automatic import sorting and code formatting
# - Integration with development workflow