vvk-charts-mcp

<p> <a href="https://github.com/valderan/vvk-charts-mcp/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-0ea5e9" /></a> <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-2563eb" /> <img alt="MCP" src="https://img.shields.io/badge/MCP-enabled-10b981" /> <img alt="Plotly" src="https://img.shields.io/badge/Plotly-modern%20charts-7c3aed" /> </p>

Documentation language:

• English: README.md
• Russian: README_ru.md

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.

<p align="center"> <img src="demo/demo_combined_dark_corporate.png" alt="Dark corporate combined dashboard example" width="560" /> <br /> <em>Example output: dark corporate combined dashboard generated by the MCP tool.</em> </p>

Table of contents

• Features
• Quick start
• MCP tools
• Combined dashboard payload example
• Terminal chart payload example
• Demo gallery
• AI presets (skill and agent)
• OpenCode setup (detailed)
• Codex setup (detailed)
• Local development

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"
      }
    }
  }
}

Demo gallery

<p> <img src="demo/demo_combined_showcase.png" alt="Combined dashboard showcase" width="420" /> <img src="demo/demo_combined_dark_corporate.png" alt="Dark corporate dashboard" width="420" /> <img src="demo/demo_combined_pastel_startup.png" alt="Pastel startup dashboard" width="420" /> </p>

<p> <img src="demo/demo_line_chart.png" alt="Line chart demo" width="270" /> <img src="demo/demo_bar_chart.png" alt="Bar chart demo" width="270" /> <img src="demo/demo_pie_chart.png" alt="Pie chart demo" width="270" /> <img src="demo/demo_scatter_chart.png" alt="Scatter chart demo" width="270" /> <img src="demo/demo_area_chart.png" alt="Area chart demo" width="270" /> </p>

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:

• https://opencode.ai/docs/mcp-servers/
• https://opencode.ai/docs/skills/
• https://opencode.ai/docs/agents/

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

• https://github.com/valderan/vvk-charts-mcp

---

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