ChartKraft Server

A professional Model Context Protocol (MCP) server for generating dynamic charts using Chart.js. Supports multiple chart types with flexible upload options and transport protocols.

✨ Features

• 📊 Multiple Chart Types: Bar, Pie, and Line charts with full customization
• 🎨 Advanced Styling: Colors, borders, fills, gradients, and animations
• 📤 Flexible Upload Options: Local temp files, AWS S3, or custom HTTP endpoints
• 🚀 Multiple Transport Protocols: Stdio, SSE, and Streamable HTTP support
• 🔧 Full TypeScript Support: Complete type safety and IntelliSense integration
• ⚡ High Performance: Optimized rendering with Chart.js 4.0+
• 🔒 Enterprise Ready: Secure upload methods and configurable environments

🚀 Quick Start

Using npx (Recommended)

# Run with default stdio transport
npx -y @yshtools/mcp-chartkraft

# Run with SSE transport on port 3000
npx -y @yshtools/mcp-chartkraft sse

# Run with HTTP transport on port 8080
npx -y @yshtools/mcp-chartkraft http --port 8080

Local Installation

npm install -g @yshtools/mcp-chartkraft
mcp-chartkraft --help
mcp-chartkraft http --port 8080

📊 Chart Tools

1. Bar Chart (create_bar_chart)

Generate vertical bar charts perfect for categorical data comparisons.

{
  "name": "create_bar_chart",
  "arguments": {
    "data": {
      "labels": ["Q1", "Q2", "Q3", "Q4"],
      "datasets": [{
        "label": "Revenue",
        "data": [120, 190, 300, 500],
        "backgroundColor": "#3498db"
      }]
    }
  }
}

2. Pie Chart (create_pie_chart)

Create circular charts for showing proportions and percentages.

{
  "name": "create_pie_chart",
  "arguments": {
    "data": {
      "labels": ["Desktop", "Mobile", "Tablet"],
      "datasets": [{
        "label": "Traffic Sources",
        "data": [60, 30, 10]
      }]
    }
  }
}

3. Line Chart (create_line_chart)

Generate line charts for time series and trend analysis.

{
  "name": "create_line_chart",
  "arguments": {
    "data": {
      "labels": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
      "datasets": [{
        "label": "Sales",
        "data": [120, 150, 180, 200, 240, 300],
        "borderColor": "#3498db",
        "tension": 0.4
      }]
    }
  }
}

⚙️ Configuration

Environment Variables

Copy env.example to .env and configure as needed:

# Upload mode: temp, aws-s3, or http
UPLOAD_MODE=temp

# Temp directory (when using temp mode)
CHART_TEMP_DIR=/tmp/charts

# AWS S3 configuration (when using aws-s3 mode)
AWS_S3_BUCKET_NAME=my-chart-bucket
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

# HTTP upload configuration (when using http mode)
HTTP_UPLOAD_URL=https://your-server.com/upload
HTTP_UPLOAD_METHOD=POST

Transport Options

Stdio (Default)

Best for direct MCP client integration:

npx -y @yshtools/mcp-chartkraft

SSE (Server-Sent Events)

For web-based clients:

npx -y @yshtools/mcp-chartkraft sse --port 3000

HTTP (Streamable)

For modern HTTP-based clients:

npx -y @yshtools/mcp-chartkraft http --port 3000

🎨 Chart Customization

Common Options

All chart types support:

• Custom dimensions: width and height in pixels
• Styling options: Colors, borders, backgrounds
• Title and legend: Positioning and visibility
• Responsive design: Auto-scaling options

Line Chart Specific

• fill: Enable area fill under the line
• tension: Control curve smoothness (0-1)
• pointRadius: Size of data points
• Point styling: Colors and borders for data points

Example with Full Options

{
  "name": "create_line_chart",
  "arguments": {
    "data": {
      "labels": ["Jan", "Feb", "Mar", "Apr", "May"],
      "datasets": [{
        "label": "Revenue",
        "data": [100, 150, 200, 180, 220],
        "borderColor": "#e74c3c",
        "backgroundColor": "rgba(231, 76, 60, 0.1)",
        "fill": true,
        "tension": 0.4,
        "pointRadius": 5
      }]
    },
    "options": {
      "plugins": {
        "title": {
          "display": true,
          "text": "Monthly Revenue"
        },
        "legend": {
          "position": "top"
        }
      },
      "scales": {
        "y": {
          "beginAtZero": true,
          "title": {
            "display": true,
            "text": "Amount ($)"
          }
        }
      }
    },
    "width": 1000,
    "height": 600
  }
}

📤 Upload Modes

1. Temp Directory (Default)

Charts are saved to system temp directory or custom path.

2. AWS S3

Upload charts directly to S3 bucket with public URLs.

3. HTTP Upload

Post charts to any HTTP endpoint that accepts file uploads.

🛠️ Development

git clone <repository>
cd mcp-chartkraft
npm install
npm run build

# Development mode
npm run dev

# Different transports
npm run dev:sse
npm run dev:http

# Test locally
npm run build
./dist/index.js --help

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Support

• 📧 Issues: GitHub Issues
• 📚 Documentation: Full Documentation
• 💬 Discussions: GitHub Discussions