🚀 Installation Guide

Get ChartSmith MCP up and running in minutes.

📋 Prerequisites

• MCP Client: Cursor, Claude Desktop, or any MCP-compatible client
• API Keys: OpenAI, Anthropic, or Google (for AI features)
• Docker (for self-deployment): Install Docker

🔗 Option 1: Connect to Hosted Service

The fastest way to get started:

npx -y @smithery/cli@latest connect "https://<YOUR_DOMAIN>/mcp"

That’s it! You now have access to all ChartSmith MCP tools.

Verify Connection

1. Open Cursor
2. Look for ChartSmith tools in the MCP panel
3. Try: “Create a simple bar chart with sample data”

🐳 Option 2: Self-Deploy with Docker

A) Prebuilt Image (Recommended)

# Pull and run HTTP (SSE) server on port 8000
docker pull inwookie/chartsmith-mcp:latest

docker run --rm \
  -p 8000:8000 \
  --env-file .env \
  inwookie/chartsmith-mcp:latest \
  python -m chart_genius_mcp --transport sse --host 0.0.0.0 --port 8000

B) From Source (clone repo)

git clone https://github.com/inwookie/chart-mcp.git
cd chart-mcp
cp env.template .env
$EDITOR .env  # add your API keys

docker compose --profile all up -d

Required settings (add your actual API key):

CHART_AI_FEATURES=true
CHART_AI_PROVIDER=openai
OPENAI_API_KEY=sk-proj-your-actual-openai-key-here

⚠️ Important: Replace sk-proj-your-actual-openai-key-here with your real OpenAI API key. Without this, AI features won’t work.

Verify deployment:

# Check containers are running
docker compose ps

# Test HTTP endpoint (SSE)
curl http://localhost:8000/health  # -> {"status":"ok"}

Step 4: Connect to Cursor

Option A: HTTP Connection (Recommended) Your ChartSmith MCP is now running at http://localhost:8000 (SSE transport). You can use any HTTP-based MCP client to connect.

Option B: STDIO Connection For STDIO MCP clients, create this wrapper script:

1. Create ~/chartsmith-mcp.sh:

   #!/bin/bash
   cd /path/to/your/chart-mcp
   docker compose run --rm chartsmith-stdio python -m chart_genius_mcp --transport stdio
   

2. Make it executable: chmod +x ~/chartsmith-mcp.sh

3. Add to ~/.cursor/mcp.json:

   {
     "mcpServers": {
    "chartsmith-local": {
      "command": "/Users/your-username/chartsmith-mcp.sh"
    }
     }
   }
   

Step 5: Restart Cursor

Close and reopen Cursor to load the new MCP connection.

🎯 Next Steps

✅ Installation Complete!

• 📊 Create Your First Chart
• 🔧 Configure Advanced Settings
• 💡 View Chart Examples

🐛 Troubleshooting

• Tools Not Showing: Restart Cursor; verify .cursor/mcp.json
• Health OK but client fails: Confirm HTTP (SSE) URL and port
• Docker issues: docker compose logs -f then docker compose restart

✅ Test Your Installation

# Test chart generation (from source compose)
docker compose run --rm chartsmith-stdio python -m chart_genius_mcp --test-chart

Expected output: ✅ Test chart generated successfully!

Generate a Real Chart File

Test creating an actual chart file:

# Create a test chart and save as HTML
docker compose run --rm chartsmith-stdio python -c "
import sys
sys.path.append('/app/src')
from chart_genius_mcp.server import ChartGeniusServer
import asyncio, json

async def save_chart():
    server = ChartGeniusServer()
    data = {'rows': [{'month': 'Jan', 'sales': 100}, {'month': 'Feb', 'sales': 120}]}
    
    result = await server._call_tool_handler('generate_bar_chart', {
        'data': data, 'x': 'month', 'y': 'sales', 'format': 'html'
    })
    
    response = json.loads(result[0].text)
    if response.get('success'):
        with open('/app/outputs/my_chart.html', 'w') as f:
            f.write(response['payload'])
        print('✅ Chart saved to outputs/my_chart.html')

asyncio.run(save_chart())
"

Then open outputs/my_chart.html in your browser to see the chart!

Common Setup Issues

“Missing API Key” or AI Features Not Working

• ✅ All tools were tested end‑to‑end. Basic charts and utilities work without API keys
• 🔑 AI tools require a real API key in .env (placeholder won’t work)
• Basic charts (no key needed): bar, line, pie, scatter, area, box, bubble, violin
• Advanced charts: work with specific parameters (e.g., heatmap needs x/y/value; sankey needs source/target/value)
• AI tools (require key): generate_chart_auto (verified), detect_optimal_chart (no key needed), analyze_and_visualize (verified), generate_chart_insights (works with chart_data dict; parameter‑sensitive)
• Get your OpenAI key from: https://platform.openai.com/api-keys

“No Such File or Directory: chart-mcp”

• Make sure you cloned the correct repo: github.com/inwookie/chart-mcp

Docker Compose Warnings

• The version warning is harmless and can be ignored

Need help? Report an issue