📡 API Reference

Complete technical documentation for ChartSmith MCP tools and resources.

✅ Tool Testing Status

Last tested: All tools verified for functionality

🎯 Basic Chart Tools (Working)

⚠️ Advanced Chart Tools (Param-specific, Verified Working)

🤖 AI-Powered Tools (Require API Keys)

🔧 Utility Tools (Verified)

Legend:

🎯 Testing Summary

🔧 Troubleshooting Complex Tools

⚠️ Tools with Parameter Format Issues

generate_histogram_chart

generate_heatmap_chart

generate_treemap_chart

generate_chart_batch

create_dashboard

export_chart

✅ Reliable Tool Alternatives

For production use, these tools are fully verified and reliable:

🛠️ Available Tools

ChartSmith MCP provides 20+ powerful tools for chart generation and data analysis.

Chart Generation Tools

generate_chart_auto

Description: Automatically detects the best chart type for your data and generates it.

Parameters:

Example:

{
  "data": {
    "columns": ["region", "sales"],
    "rows": [
      {"region": "North", "sales": 125000},
      {"region": "South", "sales": 98000},
      {"region": "East", "sales": 156000},
      {"region": "West", "sales": 87000}
    ]
  },
  "title": "Q4 Sales by Region",
  "theme": "modern"
}

generate_bar_chart

Description: Creates horizontal or vertical bar charts for categorical data comparison.

Parameters:

Example:

{
  "data": {...},
  "x_column": "product",
  "y_column": "revenue",
  "orientation": "horizontal",
  "title": "Product Revenue Comparison",
  "color_scheme": "viridis"
}

generate_line_chart

Description: Creates line charts for time series data and trend analysis.

Parameters:

Example:

{
  "data": {...},
  "x_column": "date",
  "y_column": "users",
  "show_markers": true,
  "fill_area": false,
  "title": "Monthly Active Users"
}

generate_pie_chart

Description: Creates pie charts for showing proportions and parts of a whole.

Parameters:

Example:

{
  "data": {...},
  "category_column": "department",
  "value_column": "budget",
  "chart_type": "donut",
  "show_percentages": true,
  "hole_size": 0.4
}

generate_scatter_chart

Description: Creates scatter plots for correlation analysis and relationship visualization.

Parameters:

Example:

{
  "data": {...},
  "x_column": "advertising_spend",
  "y_column": "sales_revenue",
  "size_column": "market_size",
  "show_trendline": true,
  "alpha": 0.7
}

generate_heatmap_chart

Description: Creates heatmaps for matrix data and correlation visualization.

Parameters:

Example:

{
  "data": {...},
  "x_column": "month",
  "y_column": "product",
  "value_column": "sales",
  "color_scale": "viridis",
  "show_values": true
}

AI-Powered Analysis Tools

detect_optimal_chart

Description: Uses AI to analyze your data and recommend the best chart type.

Parameters:

Returns: Recommendations with confidence scores

Example:

{
  "data": {...},
  "goal": "comparison",
  "audience": "executives"
}

analyze_and_visualize

Description: Natural language interface for creating charts from text descriptions.

Parameters:

Example:

{
  "description": "Show me how our quarterly sales have changed over the past year",
  "data": {...},
  "context": "This is for a board presentation"
}

generate_chart_insights

Description: Generates AI-powered insights and observations about your data.

Parameters:

Returns: List of insights, trends, and recommendations

Advanced Features

create_dashboard

Description: Creates multi-chart dashboards with consistent styling.

Parameters:

Example:

{
  "charts": [
    {"type": "bar", "data": {...}, "title": "Sales by Region"},
    {"type": "line", "data": {...}, "title": "Monthly Trends"}
  ],
  "layout": "grid",
  "theme": "corporate",
  "title": "Q4 Performance Dashboard"
}

generate_chart_batch

Description: Processes multiple datasets and creates charts in batch.

Parameters:

Example:

{
  "datasets": [
    {"data": {...}, "type": "bar", "title": "Chart 1"},
    {"data": {...}, "type": "line", "title": "Chart 2"}
  ],
  "common_theme": "modern",
  "output_format": "png"
}

Utility Tools

get_performance_stats

Description: Returns server performance metrics and statistics.

Returns:

Example Response:

{
  "uptime": "7d 14h 32m",
  "charts_generated": 15420,
  "avg_response_time": "145ms",
  "memory_usage": "2.1GB",
  "cache_hit_rate": "87%",
  "performance_grade": "A+"
}

🧾 Data Formats

Supported Input Formats

JSON Format

{
  "columns": ["date", "revenue", "costs"],
  "rows": [
    {"date": "2024-01", "revenue": 125000, "costs": 75000},
    {"date": "2024-02", "revenue": 132000, "costs": 78000},
    {"date": "2024-03", "revenue": 118000, "costs": 72000}
  ]
}

CSV Format

date,revenue,costs
2024-01,125000,75000
2024-02,132000,78000
2024-03,118000,72000

Array Format

[
  ["date", "revenue", "costs"],
  ["2024-01", 125000, 75000],
  ["2024-02", 132000, 78000],
  ["2024-03", 118000, 72000]
]

Output Formats

🎨 Themes & Styling

Available Themes

Color Schemes

Chart Dimensions

🔧 Configuration Options

Global Settings

{
  "theme": "modern",
  "color_scheme": "default",
  "font_family": "Arial",
  "font_size": 12,
  "dpi": 300,
  "background_color": "#ffffff",
  "grid_enabled": true,
  "legend_position": "right"
}

Performance Settings

{
  "max_data_points": 10000,
  "timeout_ms": 60000,
  "cache_enabled": true,
  "compression": true
}

📈 Response Format

Success Response

{
  "success": true,
  "chart_data": "base64_encoded_image_or_svg",
  "metadata": {
    "chart_type": "bar",
    "data_points": 156,
    "generation_time": "245ms",
    "format": "png",
    "dimensions": "800x600"
  },
  "insights": [
    "Sales increased 15% compared to previous quarter",
    "East region shows strongest growth at 23%"
  ]
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_DATA",
    "message": "Data format not recognized",
    "details": "Expected JSON object with 'columns' and 'rows' properties"
  }
}

🔗 Integration Examples

Cursor Integration

{
  "mcpServers": {
    "chartsmith": {
      "command": "docker",
      "args": ["exec", "-i", "chartsmith-mcp", "python", "-m", "chart_genius_mcp", "--transport", "stdio"]
    }
  }
}

HTTP API Usage

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "generate_bar_chart",
    "parameters": {
      "data": {...},
      "title": "Sales Report"
    }
  }'

Need more technical details? Open a GitHub discussion 🚀