Sisense MCP Server Readme

Sisense MCP Server provides integration with Sisense analytics platform. This server enables LLMs and AI assistants to interact with Sisense data models, explore data sources, and create charts using natural language prompts.

Features

• Transport Support: Streamable SSE (Server-Sent Events) for HTTP-based MCP clients

• Three MCP Tools:

  • getDataSources: Retrieve all available Sisense data sources (or data models)

  • getDataSourceFields: List all available fields for a specific data source

  • buildChart: Build charts from natural language prompts with automatic chart type detection

• Session Management: Per-session state management for chart history and context

• Chart Rendering: Automatic chart visualization with screenshot generation

• Authentication: Token-based authentication via environment variables

• TypeScript: Full type safety and modern ESM support

• Lightweight: Pure Node.js HTTP server for SSE transport

• Fast: Optimized for Bun runtime, also runs on Node.js

Prerequisites

• Bun 1.0.0 or later (recommended)
  or
  Node.js 18.0.0 or later

• Sisense instance with API access

• Sisense API token with appropriate permissions

• MCP client (e.g., Cursor, Claude Desktop, or custom client)

Installation

Using Bun (recommended):

Run the following command: bun install

With Node.js:

Run the following command: npm install

Configuration

Create a .env file in the project root:

SISENSE_URL=https://your-instance.sisense.com
SISENSE_TOKEN=your-api-token-here
PORT=3000  # Optional, defaults to 3000

Get Your Sisense API Token:

1. Log in to your Sisense instance.

2. Navigate to your user profile settings.

3. Generate an API token with appropriate permissions.

4. Copy the token to your .env file.

Using MCP

Depending on your runtime, perform one of the following actions to start the server:

Using Bun

# Development mode with hot reload
bun run dev

# Production mode (after building)
bun run build
bun run start

Using Node.js

# Development mode
npm run dev

# Production mode
npm run build
node dist/sse-server.js

The server will start and display the following:

Sisense MCP Server (SSE) running on http://localhost:3000
MCP endpoint: http://localhost:3000/mcp
Health check: http://localhost:3000/health
Screenshots: http://localhost:3000/screenshots/

The following are the API endpoints for the server:

• POST /mcp: Main MCP protocol endpoint for tool calls

• GET /mcp: SSE connection for streaming responses

• DELETE /mcp: Close MCP session

• GET /health: Health check endpoint

• GET /screenshots/:filename: Serve generated chart screenshots

MCP Client Configuration

Cursor IDE

Add the following to your Cursor MCP settings:

{
  "mcpServers": {
    "sisense": {
      "command": "bun",
      "args": ["run", "src/sse-server.ts"],
      "env": {
        "SISENSE_URL": "https://your-instance.sisense.com",
        "SISENSE_TOKEN": "your-api-token-here"
      }
    }
  }
}

If you are using a standalone server use the following:

{
  "mcpServers": {
    "sisense": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Claude Desktop

Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "sisense": {
      "command": "bun",
      "args": ["run", "src/sse-server.ts"],
      "env": {
        "SISENSE_URL": "https://your-instance.sisense.com",
        "SISENSE_TOKEN": "your-api-token-here"
      }
    }
  }
}

API Documentation

Tool: getDataSources

Function: retrieves all available data sources (data models) from your Sisense instance.

{
  "content": [
    {
      "type": "text",
      "text": "Available data sources: [\"Sample ECommerce\", \"RetailDataModel\", ...]"
    }
  ],
  "structuredContent": {
    "dataSources": [
      {
        "id": "...",
        "title": "Sample ECommerce",
        ...
      }
    ]
  }
}

{
  "content": [
    {
      "type": "text",
      "text": "Available data source fields: [...]"
    }
  ],
  "structuredContent": {
    "dataSourceTitle": "Sample ECommerce",
    "fields": [
      {
        "id": "[table.column]",
        "type": "dimension",
        "title": "column_name",
        "table": "table_name",
        ...
      }
    ]
  }
}

sisense: get data sources

Tool: getDataSourceFields

Lists all available fields for a specific data source.

{
  "content": [
    {
      "type": "text",
      "text": "Available data source fields: [...]"
    }
  ],
  "structuredContent": {
    "dataSourceTitle": "Sample ECommerce",
    "fields": [
      {
        "id": "[table.column]",
        "type": "dimension",
        "title": "column_name",
        "table": "table_name",
        ...
      }
    ]
  }
}

sisense: get fields for "Sample ECommerce"

Tool: buildChart

Creates a chart from a natural language prompt. The chart type is automatically determined by Sisense AI based on the prompt.

Input:

dataSourceTitle (string, required): The name of the data source

userPrompt (string, required): Natural language description of the chart to create

Output:

{
  "success": true,
  "chartId": "5",
  "message": "Chart created successfully for query: \"show me total revenue by month\"",
  "imageUrl": "http://localhost:3000/screenshots/widget-chart-1234567890.png"
}

Example Usage:

sisense: build chart for "Sample ECommerce" showing total revenue by month with trend

Example Prompts:

• "Show me top 10 products by sales"

• "Display revenue over time as a line chart"

• "Compare sales by region as a bar chart"

• "Show me customer distribution by age group"

Architecture

Project Structure:

sisense-mcp-server/
├── src/
│   ├── mcp-server.ts          # MCP server setup and tool registration
│   ├── sse-server.ts          # HTTP server with SSE transport
│   ├── initialize-sisense-clients.ts  # Sisense client initialization
│   ├── tools/
│   │   ├── get-data-sources.ts
│   │   ├── get-data-source-fields.ts
│   │   └── build-chart.ts
│   ├── types/
│   │   └── sessions.ts        # Session state type definitions
│   ├── utils/
│   │   ├── csdk-browser-mock.ts
│   │   ├── string-utils.ts
│   │   └── widget-renderer/   # Chart rendering with Playwright
│   └── __tests__/
│       └── mcp-client.test.ts
├── playwright/                # Playwright component testing setup
├── __screenshots__/           # Generated chart screenshots
└── package.json

Key Components

• MCP Server (mcp-server.ts): Registers and implements the three MCP tools

• SSE Server (sse-server.ts): HTTP server handling MCP protocol over SSE

• Session Management: Maintains per-session state for chart history

• Chart Renderer: Uses Playwright to render React charts and generate screenshots

• Browser Mock: Provides browser environment for Sisense SDK in Node.js

Data Flow:

1. MCP client sends tool call request > SSE server

2. SSE Server routes to MCP Server > tool handler

3. Tool handler calls Sisense SDK > Sisense API

4. Chart tool renders widget > Playwright browser

5. Screenshot saved > returned to client

Development

Development Commands

With Bun:

# Run in development mode with hot reload
bun run dev

# Build the project
bun run build

# Run tests
bun test

# Type checking
bun run type-check

# Lint
bun run lint

# Format code
bun run format

# Check formatting
bun run format:check

With Node.js:

# Run in development mode
npm run dev

# Build the project
npm run build

# Run tests
npm test

# Type checking
npm run type-check

# Lint
npm run lint

Code Structure

• Tools: Each tool is implemented in src/tools/ with its own handler function

• Types: TypeScript types for sessions and tool schemas

• Utils: Shared utilities for browser mocking and widget rendering

• Tests: Integration tests using MCP client SDK

Testing

The project includes integration tests that verify MCP tool functionality:

bun test

This uses the MCP SDK's InMemoryTransport to test tool calls without the need for a running server.

Troubleshooting

Server Will not Start

Error: "SISENSE_URL and SISENSE_TOKEN environment variables are required"

• Ensure the .env file exists and contains both variables

• Check that the environment variables are loaded correctly

Error: "Failed to initialize Sisense clients"

• Verify your Sisense URL is correct and accessible

• Check that your API token is valid and has proper permissions

• Ensure network connectivity to your Sisense instance

Tool Calls Failing

Error: "Failed to get data sources"

• Verify API token permissions allow reading data sources

• Check Sisense instance is accessible

• Review server logs for detailed error messages

Error: "Failed to create chart"

• Ensure the data source name matches exactly (case-sensitive)

• Check that the data source has the required fields for your prompt

• Review chart rendering logs for Playwright errors

Chart Rendering Issues

No screenshot generated:

• Check that Playwright browsers are installed: bunx playwright install

• Verify screenshots directory is writable

• Check server logs for rendering errors

Screenshot URL not accessible:

• Ensure server is running and accessible

• Check that screenshots endpoint is working: curl http://localhost:3000/screenshots/

MCP Client Connection Issues

Client cannot connect to server:

• Verify server is running on the expected port

• Check firewall settings

• Ensure MCP client configuration points to correct URL

Tools not appearing in client:

• Restart MCP client after server starts

• Check client logs for connection errors

• Verify MCP protocol version compatibility