Cloudera Data Visualization MCP Server

A Model Context Protocol server that exposes the full Cloudera Data Visualization (CDV) REST API to AI agents. This lets LLMs list, create, update, and delete CDV resources—groups, users, roles, segments, filter associations, workspaces, datasets, visuals, and data connections—as well as run jobs, query the data API, import/export migrations, and perform operational debugging tasks.

Tools

Groups

Users

Roles

Segments

Filter Associations

Workspaces

Datasets

Visuals

Supported visual_type values for create_smart_visual:

All other CDV chart types require configuration in CDV's interactive builder and are blocked here to prevent broken visuals.

What is blocked and why:

Connections

Migrations

Data API

Jobs

Debugging / Operations

Examples

Cloudera Agent Studio — AI Assisted Supply Chain

The screenshots below show the CDV MCP Server being used inside Cloudera Agent Studio as part of an AI-powered supply chain workflow. The user asked a natural language question and the agent automatically:

1. Discovered the available connections and datasets

2. Explored the procurement_transactions table schema

3. Planned the right visualization type and column mapping

4. Called create_smart_visual to build a stacked bar chart in CDV

5. Called create_dashboard to make it visible in the Logistics MCP Demo workspace

Prompt: "Which suppliers are driving the most urgent spend? Build a stacked bar chart in Data viz."

Step 1 — Agent plans the visualization

The agent reasons through the dataset, identifies supplier_name as the dimension, priority_code as the color grouping, and total_price (sum) as the measure, then maps these to a trellis-groupedbars visual type.

Step 2 — Visual created and linked in CDV

The agent confirms the visualization details, creates the chart via create_smart_visual, wraps it in a dashboard with create_dashboard, and returns a direct link to the new artifact in the Logistics MCP Demo workspace.

Agent Workflow Guidance

CDV Data Hierarchy

CDV organizes data in three layers, each building on the one below:

Connection  (links to an external database, e.g. Impala, Hive, Spark SQL)
  └── Dataset  (points to a specific table or query within that connection)
        └── Visual / Dashboard  (chart or dashboard built on a dataset)

Agents must respect this hierarchy when exploring or creating resources.

Discovery — Always Check Before Creating

Before creating anything, always discover what already exists at each level.

Step 1 — Connections

Call list_connections to see what data sources are registered in CDV.
Present the list to the user and identify which connection holds their data.
Only offer create_connection if no suitable connection exists and the user explicitly asks for one.

Step 2 — Datasets

Call list_datasets to see what datasets already exist (these are built on top of connections).
Present the results and ask the user which dataset to use.
Only offer create_dataset if no suitable dataset exists on the right connection and the user explicitly confirms they want a new one. Note that create_dataset requires a dc_id — the connection ID from Step 1.

Step 3 — Visuals / Dashboards

Call list_visuals to see what charts/dashboards already exist before building new ones.
Only call create_smart_visual or create_visual once the dataset has been confirmed.

Never assume anything needs to be created. CDV instances typically already have connections, datasets, and even visuals the user can reuse.

Correct flow:

User: "Build me a bar chart of shipment costs"
Agent: list_connections()            ← discover data sources
Agent: "I found these connections: ..."
Agent: list_datasets()               ← discover existing datasets
Agent: "Which dataset should I use?"
User: "Use supplier_shipping_performance"
Agent: list_workspaces()             ← identify target workspace
Agent: create_smart_visual(...)      ← now build the visual

Incorrect flow (avoid):

User: "Build me a bar chart of shipment costs"
Agent: create_connection(...)        ← ❌ never skip discovery
Agent: create_dataset(...)           ← ❌ never create without confirming first
Agent: create_smart_visual(...)

Workspace Discovery — Same Rule Applies

Always call list_workspaces before creating a visual or dashboard. Identify the correct workspace ID from the list; only call create_workspace if the user explicitly requests a new one.

Visual Creation Workflow

When create_smart_visual is used:

1. Call list_connections → understand available data sources.

2. Call list_datasets → confirm dataset with user (note which dc_id it belongs to).

3. Call list_workspaces → identify the target workspace ID.

4. Call create_smart_visual with dataset_id, workspace_id, and column specs.

   • If the Smart Visual API returns 404 (not available on all CDV instances), the tool automatically falls back to the standard admin API using the provided workspace_id.

Environment Variables

Usage with Claude Desktop

Add the following to the mcpServers section of your claude_desktop_config.json:

Option 1: Direct installation from GitHub (Recommended)

{
  "mcpServers": {
    "cdv-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/kevintalbert/cdv-mcp-server@main",
        "run-server"
      ],
      "env": {
        "CDV_BASE_URL": "https://my-cdv-instance.example.com",
        "CDV_API_KEY": "your-api-key-here",
        "CDV_USERNAME": "vizapps_admin",
        "CDV_PASSWORD": "vizapps_admin"
      }
    }
  }
}

Option 2: Local installation (after cloning the repository)

{
  "mcpServers": {
    "cdv-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/CDV-MCP-Server",
        "run",
        "src/cdv_mcp_server/server.py"
      ],
      "env": {
        "CDV_BASE_URL": "https://my-cdv-instance.example.com",
        "CDV_API_KEY": "your-api-key-here",
        "CDV_USERNAME": "vizapps_admin",
        "CDV_PASSWORD": "vizapps_admin"
      }
    }
  }
}

For Option 2, replace /path/to/CDV-MCP-Server with your local path.

Local Development

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Run the server (stdio transport, default)
uv run run-server

# Run with HTTP transport
MCP_TRANSPORT=http uv run run-server

You can also create a .env file in the project root with your credentials:

CDV_BASE_URL=https://my-cdv-instance.example.com
CDV_API_KEY=your-api-key-here
CDV_USERNAME=vizapps_admin
CDV_PASSWORD=your-cdv-password

Transport

The MCP server's transport protocol is configurable via the MCP_TRANSPORT environment variable:

• stdio (default) — communicate over standard input/output. Useful for local tools, CLI scripts, and integrations like Claude Desktop.

• http — expose an HTTP server. Useful for web-based deployments and microservices.

• sse — use Server-Sent Events (SSE) transport. Useful for existing web-based deployments that rely on SSE.

Authentication

The server uses two separate authentication mechanisms with different capability levels:

Without CDV_USERNAME / CDV_PASSWORD

When session credentials are absent, chart and dashboard creation tools are not registered in the MCP server at all — they will not appear in the agent's tool list. The server operates in a read/explore-only mode for visuals:

• ✅ query_dataapi — run SQL queries, explore data

• ✅ list_connections, list_datasets, list_workspaces — discover resources

• ✅ list_visuals, get_visual — inspect existing dashboards

• ✅ All admin tools (users, groups, roles, datasets, etc.)

• ❌ create_smart_visual — not available

• ❌ create_dashboard — not available

• ❌ create_visual / update_visual / delete_visual — not available

Why two credentials?

CDV's admin API (arc/adminapi/v1/visuals) creates visual metadata (title, type, dataset) but does not persist shelf configurations (which columns appear on which axes). Shelf data is stored through CDV's UI API (arc/reports/report/{id}), which requires a browser-style session login. Without CDV_USERNAME/CDV_PASSWORD, visuals would be created as empty skeletons that render blank in CDV's frontend.

The session is cached in memory and reused across tool calls within a server process.

Copyright (c) 2025 - Cloudera, Inc. All rights reserved.