Vvk Charts

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.

Example output: dark corporate combined dashboard generated by the MCP tool.

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

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