Skip to main content
Glama
vvk-charts-mcp

vvk-charts-mcp

by valderan

vvk-charts-mcp

Documentation language:

Modern Python MCP server for rendering charts and diagrams (line, bar, pie, scatter, area, and combined dashboard) with customizable themes and export to PNG/SVG/base64.

Table of contents

Related MCP server: mcp-plots

Features

  • MCP tools for single charts and mixed dashboards.

  • Terminal chart tools with ANSI rendering and monochrome fallback.

  • Modern Plotly styling with full theme customization.

  • Works with multi-series and larger datasets.

  • Export formats: png, svg, base64.

  • Interactive CLI test client with predefined templates.

Quick start

Install from GitHub with uvx:

uvx install git+https://github.com/valderan/vvk-charts-mcp.git

Run MCP server:

uvx run vvk-charts-mcp

Run interactive test client:

uvx run vvk-charts-cli

The CLI asks what to draw, where to save, output format, and image size.

Tip: set output mode to terminal in vvk-charts-cli to preview console dashboards.

MCP tools

Tool

Purpose

list_theme_presets

Lists available image/terminal themes

create_line_chart

Trends over time

create_bar_chart

Category comparison

create_pie_chart

Part-to-whole split

create_scatter_chart

Correlation and bubble plots

create_area_chart

Stacked/cumulative composition

create_combined_dashboard

Multiple chart types in one image

create_terminal_chart

ANSI/mono chart output for terminal clients

create_terminal_dashboard

Multi-panel terminal dashboard as plain text

Common options supported by all tools:

  • theme_preset, theme, title, width, height

  • format (png, svg, base64)

  • filename, save_to_disk

Image tools always return chat preview (ImageContent). To save files, set save_to_disk: true and configure OUTPUT_DIR in MCP env.

Theme presets

Use list_theme_presets to get all available theme names at runtime.

Image theme presets:

  • clean_light (default)

  • dark_corporate

  • pastel_startup

  • medical_monitor

Terminal theme presets:

  • dark_corporate_cli (default)

  • pastel_startup_cli

Example request:

{
  "tool": "list_theme_presets",
  "arguments": {}
}

Combined dashboard payload example

{
  "title": "Marketing Dashboard",
  "rows": 1,
  "cols": 2,
  "theme_preset": "dark_corporate",
  "format": "png",
  "save_to_disk": true,
  "filename": "combined_dashboard",
  "panels": [
    {
      "type": "line",
      "row": 1,
      "col": 1,
      "title": "Revenue Trend",
      "x_label": "Month",
      "y_label": "k USD",
      "data": [
        {
          "name": "Revenue",
          "x": ["Jan", "Feb", "Mar", "Apr"],
          "y": [120, 132, 148, 160]
        }
      ],
      "options": {
        "line_shape": "spline"
      }
    },
    {
      "type": "pie",
      "row": 1,
      "col": 2,
      "title": "Budget Split",
      "data": [
        {
          "labels": ["Search", "Social", "Email"],
          "values": [45, 35, 20]
        }
      ],
      "options": {
        "hole": 0.45
      }
    }
  ]
}

Terminal chart payload example

{
  "tool": "create_terminal_chart",
  "arguments": {
    "type": "line",
    "title": "Revenue Trend (CLI)",
    "x_label": "Month",
    "y_label": "k USD",
    "theme": "dark_corporate_cli",
    "use_color": true,
    "force_mono": false,
    "raw_output": true,
    "data": [
      {
        "name": "Revenue",
        "x": ["Jan", "Feb", "Mar", "Apr", "May"],
        "y": [120, 132, 148, 160, 178]
      }
    ]
  }
}

raw_output: true is recommended for terminal clients: tool returns only chart text (no JSON wrapper).

Image save behavior (OUTPUT_DIR)

  • save_to_disk: false (default): no file is written, preview is returned to chat.

  • save_to_disk: true and OUTPUT_DIR is set: file is saved only into OUTPUT_DIR.

  • save_to_disk: true and OUTPUT_DIR is not set: no error, preview only (saved=false in metadata).

  • output_path is not supported.

Example MCP config fragment:

{
  "mcp": {
    "vvkcharts": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "--from", "git+https://github.com/valderan/vvk-charts-mcp.git", "vvk-charts-mcp"],
      "env": {
        "OUTPUT_DIR": "./output"
      }
    }
  }
}

AI presets (skill and agent)

Repository includes reusable AI presets in ai/:

  • ai/vvk-charts-skill.md - skill instructions for chart payload building.

  • ai/vvk-charts-agent.md - chart-specialized subagent profile.

Use whichever workflow is more convenient.

OpenCode setup (detailed)

1) Add this MCP server

Create or edit opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vvkcharts": {
      "type": "local",
      "enabled": true,
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/valderan/vvk-charts-mcp.git",
        "vvk-charts-mcp"
      ]
    }
  }
}

2) Install as an OpenCode skill

mkdir -p .opencode/skills/vvk-charts-mcp
cp ai/vvk-charts-skill.md .opencode/skills/vvk-charts-mcp/SKILL.md

3) Install as an OpenCode agent

mkdir -p .opencode/agents
cp ai/vvk-charts-agent.md .opencode/agents/vvk-charts.md

4) Verify

  • Start opencode in this repository.

  • Ensure vvkcharts_* tools are visible.

  • Test prompt: Build a monthly revenue line chart and save as png in ./output using vvkcharts.

References:

Codex setup (detailed)

Codex-compatible clients may vary, but this flow works in MCP-enabled environments.

1) Register MCP server

uvx --from git+https://github.com/valderan/vvk-charts-mcp.git vvk-charts-mcp

Typical JSON shape used by many clients:

{
  "mcpServers": {
    "vvkcharts": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/valderan/vvk-charts-mcp.git",
        "vvk-charts-mcp"
      ]
    }
  }
}

2) Reuse skill and agent presets

  • Use ai/vvk-charts-skill.md as a reusable prompt template.

  • Use ai/vvk-charts-agent.md as a dedicated chart profile/system prompt.

3) Verify

Run a request like:

Use vvkcharts tools to generate a bar chart and save it to ./output/sales-q1.png.

Local development

uv sync
uv run ruff check .
uv run mypy src

Repository


Русская версия документации: README_ru.md

Available Tools

9 tools
create_area_chartB

Создаёт диаграмму с областями с поддержкой стекинга. Возвращает base64 изображение или путь к файлу.

Inputs: data (required), stack, theme, title, +10 more.

create_bar_chartB

Создаёт столбчатую диаграмму с поддержкой группировки и стекинга. Возвращает base64 изображение или путь к файлу.

Inputs: data (required), theme, title, width, +9 more.

create_combined_dashboardB

Создаёт комбинированный дашборд из нескольких графиков и диаграмм на одном изображении.

Inputs: panels (required), cols, rows, theme, +10 more.

create_line_chartB

Создаёт линейный график с поддержкой множественных серий данных. Возвращает base64 изображение или путь к файлу.

Inputs: data (required), theme, title, width, +9 more.

create_pie_chartB

Создаёт круговую диаграмму с поддержкой doughnut. Возвращает base64 изображение или путь к файлу.

Inputs: data (required), hole, theme, title, +7 more.

create_scatter_chartA

Создаёт точечный график с поддержкой пузырьковых диаграмм. Возвращает base64 изображение или путь к файлу.

Inputs: data (required), theme, title, width, +8 more.

create_terminal_chartC

Рисует график для консоли (ANSI с авто-fallback в монохром).

Inputs: data (required), type (required), theme, title, +8 more.

create_terminal_dashboardC

Рисует текстовый дашборд для консоли из нескольких панелей.

Inputs: panels (required), theme, title, width, +5 more.

list_theme_presetsA

Возвращает список доступных тем для image и terminal графиков, чтобы выбрать тему без чтения документации.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct chart type or output format: line, bar, pie, scatter, area, combined dashboard, terminal chart, and terminal dashboard. The only pair with potential overlap is the two dashboards, but one is explicitly image-based and the other is explicitly terminal-based.

    Naming Consistency5/5

    Tool names follow a consistent snake_case verb_noun pattern, with create_*_chart for individual chart types and create_*_dashboard for dashboard variants. The list_theme_presets tool also fits the pattern by using a list verb.

    Tool Count5/5

    Nine tools is well-scoped for a charting server, covering the main chart types, dashboards, terminal output, and theme discovery. Each tool has a clear responsibility and none feel redundant.

    Completeness5/5

    The tool surface covers the major standard chart types, multi-chart dashboards, terminal-specific charts, and theme selection. Since this is a stateless chart-generation server rather than a CRUD system, the absence of update/delete operations is not a gap.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      A Model Context Protocol server that generates lightweight ASCII charts directly in terminal environments, supporting line charts, bar charts, scatter plots, histograms, and sparklines without GUI dependencies.
      5
      15 npm
      9
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A MCP server for data visualization. It exposes tools to render charts (line, bar, pie, scatter, heatmap, etc.) from data and returns plots as either image/text/mermaid diagram.
      2
      4
      MIT