Cube.js MCP Server

A Model Context Protocol (MCP) server implementation for Cube.js, enabling seamless integration between AI assistants and Cube.js analytics platforms.

Overview

This project provides a FastMCP-based server that exposes Cube.js analytics capabilities through the Model Context Protocol. It allows AI models and applications to:

• List available data cubes and their metadata

• Query data using natural language-friendly interfaces

• Access measures, dimensions, and segments from your Cube.js instance

• Execute complex analytics queries programmatically

Features

• Cube Listing: Retrieve all available cubes with their measures, dimensions, and segments

• Query Support: Execute queries against Cube.js with flexible filtering and aggregation

• Metadata Access: Get detailed information about cube structure and relationships

• Async Support: Built on FastMCP for high-performance async operations

• Error Handling: Robust error handling with meaningful error messages

• Token Authentication: Secure API access with token-based authentication

Prerequisites

• Python 3.8 or higher

• Cube.js instance running and accessible

• pip package manager

Installation

1. Clone the repository:

2. Install dependencies:

3. Set up environment variables:

Edit .env with your Cube.js configuration:

Configuration

Environment Variables

• CUBEJS_API_BASE_URL: The base URL of your Cube.js API (default: http://localhost:4000/cubejs-api/v1)

• CUBEJS_API_TOKEN: Authentication token for Cube.js API (required if your instance requires authentication)

Claude Configuration

To use this MCP server with Claude or other compatible clients, add it to your configuration file (~/.config/Claude/claude_desktop_config.json):

Usage

Running the Server

The server will start and be ready to accept MCP protocol requests.

Available Tools

1. list_cubes()

Retrieves the list of available cubes with their metadata.

Returns: A dictionary containing:

• Cube names and descriptions

• Available measures for each cube

• Available dimensions for each cube

• Available segments for each cube

Example:

2. query_cube(cube_name, measures, dimensions, filters)

Execute a query against a specific cube.

Parameters:

• cube_name (string): Name of the cube to query

• measures (list): List of measures to include in the query

• dimensions (list): List of dimensions to group by

• filters (optional, list): List of filter conditions

Returns: Query results with aggregated data

Example:

Project Structure

Dependencies

• fastmcp: FastMCP framework for building MCP servers

• httpx: Async HTTP client for making requests to Cube.js

• python-dotenv: Environment variable management

See requirements.txt for specific versions.

Error Handling

The server includes comprehensive error handling for:

• Network connectivity issues

• Authentication failures

• Invalid cube or metric names

• API rate limiting

• Malformed queries

Error responses include descriptive messages to help diagnose issues.

Security Considerations

• Always keep your CUBEJS_API_TOKEN secret and never commit it to version control

• Use .env files with proper permissions (600 or restricted access)

• Consider using environment variables managed by your deployment platform

• Ensure your Cube.js instance is properly secured behind authentication/firewall

Development

Setting up Development Environment

Running Tests

Tests can be added to verify functionality. Use pytest or unittest frameworks.

Troubleshooting

Connection Issues

• Verify CUBEJS_API_BASE_URL is correct and Cube.js is running

• Check network connectivity to the Cube.js instance

• Ensure firewall allows connections

Authentication Errors

• Confirm CUBEJS_API_TOKEN is correct

• Check if your Cube.js instance requires authentication

• Verify token hasn't expired

Query Errors

• Ensure cube names, measures, and dimensions are spelled correctly

• Check if filters are properly formatted

• Verify you have permission to access the requested cubes

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Submit a pull request

License

This project is open source and available under the MIT License.

Support

For issues, questions, or suggestions, please open an issue on the GitHub repository.

Resources

• Cube.js Documentation

• Model Context Protocol

• FastMCP Documentation