Content
# 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`](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](#features)
- [Quick start](#quick-start)
- [MCP tools](#mcp-tools)
- [Combined dashboard payload example](#combined-dashboard-payload-example)
- [Terminal chart payload example](#terminal-chart-payload-example)
- [Demo gallery](#demo-gallery)
- [AI presets (skill and agent)](#ai-presets-skill-and-agent)
- [OpenCode setup (detailed)](#opencode-setup-detailed)
- [Codex setup (detailed)](#codex-setup-detailed)
- [Local development](#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`:
```bash
uvx install git+https://github.com/valderan/vvk-charts-mcp.git
```
Run MCP server:
```bash
uvx run vvk-charts-mcp
```
Run interactive test client:
```bash
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:
```json
{
"tool": "list_theme_presets",
"arguments": {}
}
```
## Combined dashboard payload example
```json
{
"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
```json
{
"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:
```json
{
"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`:
```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
```bash
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
```bash
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
```bash
uvx --from git+https://github.com/valderan/vvk-charts-mcp.git vvk-charts-mcp
```
Typical JSON shape used by many clients:
```json
{
"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
```bash
uv sync
uv run ruff check .
uv run mypy src
```
## Repository
- https://github.com/valderan/vvk-charts-mcp
---
Русская версия документации: [`README_ru.md`](README_ru.md)
