Skip to main content
Glama
mob999

@mob999/cube_mcp

by mob999
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Cube.js TypeScript MCP Server

This is a standalone Model Context Protocol (MCP) server for Cube.js, written in TypeScript using the official @cubejs-client/core SDK.

It provides advanced AI assistants (like Claude, Cursor, etc.) with semantic layer visibility and multi-dimensional querying capabilities over your data.

Features

  • discover_entities: Introspects the Cube.js metadata (/meta) and explains the available Cubes, Dimensions, and Measures to the LLM.

  • execute_query: Executes semantic queries (/load) with support for Cube query fields like filters, sorting, time dimensions, pagination, timezone, and result truncation.

Related MCP server: Cube MCP Server

Prerequisites

  • Node.js (v18 or higher recommended)

  • A running instance of Cube.js

Quick Start

You can run the published MCP server directly without installing it manually:

npx -y @mob999/cube_mcp

Local Development & Build

  1. Install dependencies:

    npm install

  2. Build the TypeScript source:

    npm run build

    This compiles the TypeScript code into the dist/ directory.

Development & Testing

  • Run Tests: npm test

  • Lint Code: npm run lint

Query Features

execute_query supports:

  • measures

  • dimensions

  • filters

  • timeDimensions

  • segments

  • limit

  • rowLimit

  • offset

  • order

  • timezone

  • renewQuery

  • ungrouped

  • responseFormat

  • total

Example:

{
  "entity_name": "Components",
  "measures": ["Components.count"],
  "dimensions": ["Components.id"],
  "timeDimensions": [
    {
      "dimension": "Components.createdAt",
      "granularity": "day",
      "dateRange": ["2026-01-01", "2026-01-31"]
    }
  ],
  "order": [
    { "member": "Components.count", "direction": "desc" },
    { "member": "Components.id", "direction": "asc" }
  ],
  "limit": 100,
  "rowLimit": 500,
  "offset": 0,
  "timezone": "UTC",
  "responseFormat": "compact",
  "total": true
}

Configuration

By default, the server expects your Cube.js API to be available at http://localhost:4000/cubejs-api/v1.

You can override this by setting the CUBEJS_API_URL environment variable.

To integrate this semantic layer into Cursor or any other MCP-compatible IDE/Agent, configure it as a stdio tool.

Example mcp.json / Client Configuration:

{
  "mcpServers": {
    "CubeSemanticLayer": {
      "command": "npx",
      "args": ["-y", "@mob999/cube_mcp"],
      "env": {
        "CUBEJS_API_URL": "http://localhost:4000/cubejs-api/v1"
      }
    }
  }
}

Note: The -y flag allows npx to automatically download and run the package without prompting for confirmation.

Available Tools

2 tools
discover_entitiesA

Discover available Data Assets (Entities). Use this tool FIRST to understand the schema (Dimensions and Measures) available for querying. Returns a catalog of Semantic Entities with descriptions of their fields.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the return value as 'a catalog of Semantic Entities with descriptions of their fields' and implies a read-only discovery operation. However, it does not mention potential limits, entity visibility, or data freshness, which would provide richer behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no filler. The key directive is front-loaded ('Use this tool FIRST') and each sentence earns its place by covering what, when, and what to expect.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, no output schema, and a simple discovery use case, the description covers all necessary aspects: purpose, usage timing, and return content. The only minor gap is not naming the sibling directly, but the 'FIRST' and 'for querying' phrasing sufficiently implies the distinction.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4 according to the rubric. The empty input schema fully covers parameter documentation, and the description correctly adds no unnecessary parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb and resource: 'Discover available Data Assets (Entities)' and explains its role as understanding the schema (Dimensions and Measures). It differentiates from the sibling by positioning itself as a prerequisite to querying, though it does not name execute_query explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to use this tool FIRST to understand the schema before querying, giving clear context of when it should be used. It does not state exclusions or directly name the alternative tool, which prevents a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

execute_queryA

Execute an Analytical Query. Perform multi-dimensional analysis on one of the entities discovered via 'discover_entities'.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax rows to return (default None).
orderNoOptional multi-column sort rules applied in order.
totalNoOptional Cube total flag.
offsetNoOptional row offset.
filtersNoOptional filters to apply to the query.
measuresNoMeasures to calculate (e.g., ['Components.area']). MUST use 'Entity.Measure' format.
rowLimitNoOptional Cube rowLimit.
segmentsNoOptional Cube segments.
timezoneNoOptional query timezone, for example 'UTC' or 'Asia/Shanghai'.
ungroupedNoOptional Cube ungrouped flag.
dimensionsNoDimensions to group/segment by (e.g., ['Components.id']). MUST use 'Entity.Dimension' format.
renewQueryNoOptional Cube renewQuery flag.
entity_nameYesThe name of the Entity to query (e.g., 'Components').
responseFormatNoOptional Cube response format.
timeDimensionsNoOptional Cube time dimensions.

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. 'Execute an Analytical Query' and 'multi-dimensional analysis' imply a read-oriented computation, but the description does not mention whether any state changes occur, how results are returned, pagination behavior, or potential performance/rate-limit concerns. For a query tool this is a notable gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The core purpose is front-loaded, and the discover_entities dependency is stated in the second sentence. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a complex tool with 15 parameters, no output schema, and no annotations. The description covers the prerequisite workflow (discover_entities) but omits any guidance on the return format, required parameter combinations, or the analytical intent behind the many Cube flags. An agent would need to rely heavily on the schema alone, which is not enough for such a configurable tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 15 parameters, establishing a baseline of 3. The description adds a meaningful connection between entity_name and the discover_entities workflow, but it does not meaningfully clarify the many Cube-specific options (filters, timeDimensions, renewQuery, etc.) beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Execute') and resource ('Analytical Query'), and further clarifies with 'Perform multi-dimensional analysis on one of the entities discovered via discover_entities.' This clearly distinguishes it from the only sibling, discover_entities, which focuses on discovery rather than querying.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly frames the tool as operating on entities discovered via 'discover_entities', establishing a clear prerequisite and workflow. It tells the agent when this tool is appropriate, though it does not enumerate explicit alternatives or negative cases. Since the sibling set is minimal, this is sufficient guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.7
    • First observeddiscover_entities
    • First observedexecute_query
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 2 tools

Disambiguation5/5

The two tools serve clearly different stages of the workflow: one discovers available entities/schema and the other executes queries against them. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tool names follow the same verb_noun snake_case pattern: discover_entities and execute_query. The naming is consistent and conveys the action clearly.

Tool Count3/5

Two tools is at the thin end of the range, but the pair forms a minimal coherent workflow for semantic analytics. The count feels slightly under-provisioned rather than excessive.

Completeness4/5

The core lifecycle of discovery-then-query is covered, allowing an agent to find entities and run analytical queries. Minor gaps exist, such as no dedicated metadata or validation tools, but they are not essential to the primary purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Cube.js MCP Server

    zsembek
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to query and analyze data from Cube.js analytics platforms, allowing natural language access to cubes, measures, dimensions, and complex analytics queries.
    9
    MIT

  • Cube MCP Server

    cubedevinc
    A
    license
    B
    quality
    D
    maintenance
    Enables users to interact with Cube's AI agent for real-time analytics and data exploration through a chat interface. It supports generating data visualizations, performing SQL queries, and analyzing trends using natural language.
    1
    13 npm
    13
    MIT

  • DB-MCP

    scrappymonkey
    A
    license
    B
    quality
    D
    maintenance
    An MCP server that bridges AI assistants with data warehouses through Cube.js to enable governed, natural language semantic analytics queries. It provides tools for metadata discovery and secure query execution while enforcing governance policies like PII blocking and access limits.
    3
    47 npm
    1
    MIT
  • Foggy Data MCP Bridge by foggy-projects

    Foggy Data MCP Bridgeofficial

    foggy-projects
    A
    license
    Not graded
    quality
    D
    maintenance
    A semantic layer query engine with MCP support, enabling AI assistants to query structured data through natural language and declarative interfaces.
    2
    Apache 2.0