Content
# Cube.js TypeScript MCP Server
This is a standalone Model Context Protocol (MCP) server for [Cube.js](https://cube.dev/), 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.
## 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:
```bash
npx -y @mob999/cube_mcp
```
## Local Development & Build
1. **Install dependencies:**
```bash
npm install
```
2. **Build the TypeScript source:**
```bash
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:
```json
{
"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:**
```json
{
"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.*
