CanvasXpress

You can run a dedicated MCP server that turns natural language into CanvasXpress configurations. The server supports HTTP access for multiple clients and a STDIO mode for local integrations, enabling you to generate charts and visualizations quickly from descriptions. It offers flexible LLM and embedding options and comes with a tested vector database of 132 few-shot examples to improve accuracy.

How to use

You will interact with the CanvasXpress MCP Server through an MCP client or via a local STDIO workflow. For remote usage, run the HTTP mode so you can access the service at a stable URL from multiple clients. For Claude Desktop or other local integrations, use the STDIO workflow to connect to the server on the same machine.

How to install

Prerequisites you must have before starting:

• Docker installed and running or Python 3.10+ for a local virtual environment

Step 1: Prepare your environment

git clone https://github.com/bms-ips/canvasxpress-mcp-server.git
cd canvasxpress-mcp-server
cp .env.example .env

Step 2: Configure environment variables

Edit your environment file to specify your LLM and embedding providers. You can choose Azure OpenAI with local embeddings or Google Gemini with cloud embeddings.

Azure OpenAI (BMS) with local embeddings

LLM_PROVIDER=openai
AZURE_OPENAI_KEY=your_key_from_genai.web.bms.com
LLM_MODEL=gpt-4o-global
LLM_ENVIRONMENT=nonprod
EMBEDDING_PROVIDER=local  # BGE-M3 (highest accuracy)

Google Gemini (fully cloud-based)

LLM_PROVIDER=gemini
GOOGLE_API_KEY=your_key_from_aistudio.google.com
GEMINI_MODEL=gemini-2.0-flash-exp
EMBEDDING_PROVIDER=gemini

Step 3: Choose your setup

Option A: Docker (Full) is the default and provides a complete environment with local embeddings.

Option B: Local Venv (Lightweight) is for smaller servers and uses cloud embeddings.

Option A: Docker (Full)

make build      # Build Docker image
make init       # Initialize vector DB (downloads BGE-M3 ~2GB)
make run-http   # Start server in HTTP mode

Option B: Local Venv (Lightweight)

make venv-light  # Create lightweight venv (~500MB, no PyTorch)
make init-local  # Initialize vector DB (uses cloud embeddings)
make run-local   # Start server in HTTP mode

Step 4: Test the server

Use the CLI client or run a quick test inside your container to confirm the server responds with a chart configuration.

Next steps after install

• You can test with: `python3 mcp_cli.py -q

Tools and endpoints

The server provides a single tool to generate CanvasXpress configurations directly from natural language.

Tool name: generate_canvasxpress_config. Description: Generates a CanvasXpress JSON configuration from a natural language description, optionally using dataset headers and a temperature setting to influence creativity.

Configuration and security notes

The server supports multiple providers for LLMs and embeddings. Configure in a local environment file. Ensure you keep API keys secure and do not expose them in shared environments.

Troubleshooting

• If the server won’t start, check logs with the appropriate command and ensure the environment variables are set.

Examples and usage patterns

• Create a bar chart description and receive a CanvasXpress JSON configuration suitable for rendering the chart.

Available tools

generate_canvasxpress_config

Generates a CanvasXpress JSON configuration from a natural language description, optionally using dataset headers and a temperature setting to influence creativity.