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
- Clone the repository:
git clone https://github.com/zsembek/Cube.js-MCP-server.git
cd Cube.js-MCP-server
- Install dependencies:
pip install -r requirements.txt
- Set up environment variables:
cp .env.example .env
Edit .env with your Cube.js configuration:
CUBEJS_API_BASE_URL=http://localhost:4000/cubejs-api/v1
CUBEJS_API_TOKEN=your_api_token_here
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):
{
"mcpServers": {
"cubejs": {
"command": "uvx",
"args": [
"--with",
"cubejs-mcp-server @ git+https://github.com/zsembek/Cube.js-MCP-server.git",
"python",
"-m",
"cubejs_mcp.server"
],
"env": {
"CUBEJS_API_BASE_URL": "http://localhost:4000/cubejs-api/v1",
"CUBEJS_API_TOKEN": "your_api_token"
}
}
}
}
Usage
Running the Server
python server.py
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:
cubes = await list_cubes()
2. query_cube(cube_name, measures, dimensions, filters)
Execute a query against a specific cube.
Parameters:
cube_name(string): Name of the cube to querymeasures(list): List of measures to include in the querydimensions(list): List of dimensions to group byfilters(optional, list): List of filter conditions
Returns: Query results with aggregated data
Example:
result = await query_cube(
cube_name="Orders",
measures=["Orders.count", "Orders.total"],
dimensions=["Orders.status"],
filters=["Orders.created_date > 2024-01-01"]
)
Project Structure
.
├── cubejs_mcp/
│ ├── __init__.py # Package initialization
│ └── server.py # MCP server implementation
├── server.py # Legacy entry point (kept for compatibility)
├── config.json # Configuration file for MCP clients
├── pyproject.toml # Python package configuration
├── requirements.txt # Python dependencies
├── .env.example # Environment variables template
└── README.md # This file
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_TOKENsecret and never commit it to version control - Use
.envfiles 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
# Install dependencies
pip install -r requirements.txt
# Set up environment variables
cp .env.example .env
# Edit .env with your local Cube.js instance details
nano .env
Running Tests
Tests can be added to verify functionality. Use pytest or unittest frameworks.
Troubleshooting
Connection Issues
- Verify
CUBEJS_API_BASE_URLis correct and Cube.js is running - Check network connectivity to the Cube.js instance
- Ensure firewall allows connections
Authentication Errors
- Confirm
CUBEJS_API_TOKENis 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:
- Fork the repository
- Create a feature branch
- Make your changes
- 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.