[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_111":112},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":48,"_57":58,"_59":60,"_61":-5,"_62":-5,"_63":-5,"_64":-5,"_65":66,"_67":68,"_69":70,"_71":72,"_73":74,"_75":-5,"_76":-5,"_77":-5,"_78":48,"_79":-5,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91},"apiUrl","https://odel.app/api","creator","mr901","moduleId","mcp-plots","@mr901/mcp-plots","displayName","mcp plots","tagline","MCP server for data visualization with Mermaid charts.","iconKey","https://avatars.githubusercontent.com/u/20877166?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1783335514000,"updatedAt",1788775839000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.MR901%2Fmcp-plots","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",4,"upstreamUpdatedAt",1764644381000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/MR901/mcp-plots","githubRepoFullName","MR901/mcp-plots","releaseId","ext-mr901-mcp-plots","version","0.0.3","descriptionMarkdown","

\n\n

Plots MCP Server

\n\n[![PyPI](https://img.shields.io/pypi/v/mcp-plots)](https://pypi.org/project/mcp-plots/) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/mcp-plots?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=BRIGHTGREEN&left_text=downloads)](https://pepy.tech/projects/mcp-plots) [![Smithery](https://smithery.ai/badge/@MR901/mcp-plots)](https://smithery.ai/server/@MR901/mcp-plots) [![Glama](https://img.shields.io/badge/Glama-Listing-8A2BE2)](https://glama.ai/mcp/servers/@MR901/mcp-plots) [![Python Versions](https://img.shields.io/pypi/pyversions/mcp-plots)](https://pypi.org/project/mcp-plots/) [![License](https://img.shields.io/github/license/mr901/mcp-plots)](LICENSE)\n\n\n

\n\n\n

\n\n
\nA Model Context Protocol (MCP) server for data visualization. It exposes tools to render charts (line, bar, pie, scatter, heatmap, etc.) from data and returns the plot as image/base64 text/mermaid diagram.\n\n\n\n## Why MCP Plots?\n\n- Instant, visual-first charts using Mermaid (renders directly in MCP clients like Cursor)\n- Simple prompts to generate charts from plain data\n- Zero-setup options via uvx, or install from PyPI/Docker\n- Flexible output formats: mermaid (default), PNG image, or text\n\n## Quick Usage\n\n- Ask your MCP client: \"Create a bar chart showing sales: A=100, B=150, C=80\"\n- Default output is Mermaid, so diagrams render instantly in Cursor\n\n## Quick Start\n\n### PyPI Installation (Recommended)\n```bash\npip install mcp-plots\nmcp-plots # Start the server\n```\n\n### For Cursor Users\n1. Install the package: `pip install mcp-plots`\n2. Add to your Cursor MCP config (`~/.cursor/mcp.json`):\n ```json\n {\n \"mcpServers\": {\n \"plots\": {\n \"command\": \"mcp-plots\",\n \"args\": [\"--transport\", \"stdio\"]\n }\n }\n }\n ```\n Alternative (zero-install via uvx + PyPI):\n ```json\n {\n \"mcpServers\": {\n \"plots\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-plots\", \"--transport\", \"stdio\"]\n }\n }\n }\n ```\n3. Restart Cursor\n4. Ask: *\"Create a bar chart showing sales: A=100, B=150, C=80\"*\n\n### Development Installation\n```bash\nuvx --from git+https://github.com/mr901/mcp-plots.git run-server.py\n```\n\n**[Documentation →](https://github.com/MR901/mcp-plots/blob/main/docs/README.md)** | **[Quick Start →](https://github.com/MR901/mcp-plots/blob/main/docs/quickstart.md)** | **[API Reference →](https://github.com/MR901/mcp-plots/blob/main/docs/api.md)**\n\n## MCP Registry\n\nThis server is published under the MCP registry identifier `io.github.MR901/mcp-plots`. You can discover/verify it via the official registry API:\n\n```bash\ncurl \"https://registry.modelcontextprotocol.io/v0/servers?search=io.github.MR901/mcp-plots\"\n```\n\nRegistry metadata for this project is tracked in `server.json`.\n\n## Install with Smithery\n\nThis repository includes a `smithery.yaml` for easy setup with Smithery.\n\n- File: `smithery.yaml`\n- Docs: https://smithery.ai/docs/config#smitheryyaml\n\nExample install using the Smithery CLI (adjust `--client` as needed, e.g. `cursor`, `claude`):\n\n```bash\nnpx -y @smithery/cli install \\\n https://raw.githubusercontent.com/mr901/mcp-plots/main/smithery.yaml \\\n --client cursor\n```\n\nAfter installation, your MCP client should be able to start the server over stdio using the command defined in `smithery.yaml`.\n\n## Project layout\n\n```\nsrc/\n app/ # Server construction and runtime\n server.py\n capabilities/ # MCP tools and prompts\n tools.py\n prompts.py\n visualization/ # Plotting engines and configurations\n chart_config.py\n generator.py\n```\n\n## Requirements\n\n- Python 3.10+\n- See `requirements.txt`\n\n## Setup Routes\n\n### uvx (Recommended)\n\nThe easiest way to run the MCP server without managing Python environments:\n\n```bash\n# Run directly with uvx (no installation needed)\nuvx --from git+https://github.com/mr901/mcp-plots.git run-server.py\n\n# Or install and run the command\nuvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots\n\n# With custom options\nuvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --port 8080 --log-level DEBUG\n```\n\n**Why uvx?**\n- **No Environment Management**: Automatically handles Python dependencies\n- **Isolated Execution**: Runs in its own virtual environment\n- **Always Latest**: Pulls fresh code from repository\n- **Zero Setup**: Works immediately without pip install\n- **Cross-Platform**: Same command works on Windows, macOS, Linux\n\n### PyPI (Traditional Installation)\n\n1) **Install dependencies**\n```bash\npip install -r requirements.txt\n```\n\n2) **Run the server (HTTP transport, default port 8000)**\n```bash\npython -m src --transport streamable-http --host 0.0.0.0 --port 8000 --log-level INFO\n```\n\n3) **Run with stdio (for MCP clients that spawn processes)**\n```bash\npython -m src --transport stdio\n```\n\n### Local Development (from source)\n```bash\ngit clone https://github.com/mr901/mcp-plots.git\ncd mcp-plots\npip install -e .\npython -m src --transport stdio --log-level DEBUG\n```\n\n### Docker\n\n```bash\ndocker build -t mcp-plots .\ndocker run -p 8000:8000 mcp-plots\n```\n\nEnvironment variables (optional):\n- `MCP_TRANSPORT` (streamable-http|stdio)\n- `MCP_HOST` (default 0.0.0.0)\n- `MCP_PORT` (default 8000)\n- `LOG_LEVEL` (default INFO)\n\n## Tools\n\n- `list_chart_types()` → returns available chart types\n- `list_themes()` → returns available themes\n- `suggest_fields(sample_rows)` → suggests field roles based on data samples\n- `render_chart(chart_type, data, field_map, config_overrides?, options?, output_format?)` → returns MCP content\n- `generate_test_image()` → generates a test image (red circle) to verify MCP image support\n\n### Cursor Integration\n\nThis MCP server is **fully compatible with Cursor's image support**! When you use the `render_chart` tool:\n\n- **Charts appear directly in chat** - No need to save files or open separate windows\n- **AI can analyze your charts** - Vision-enabled models can discuss and interpret your visualizations\n- **Perfect MCP format** - Uses the exact base64 PNG format that Cursor expects\n\nThe server returns images in the MCP format Cursor requires:\n```json\n{\n \"content\": [\n {\n \"type\": \"image\", \n \"data\": \"\",\n \"mimeType\": \"image/png\"\n }\n ]\n}\n```\n\nExample call (pseudo):\n```\nrender_chart(\n chart_type=\"bar\",\n data=[{\"category\":\"A\",\"value\":10},{\"category\":\"B\",\"value\":20}],\n field_map={\"category_field\":\"category\",\"value_field\":\"value\"},\n config_overrides={\"title\":\"Example Bar\",\"width\":800,\"height\":600,\"output_format\":\"MCP_IMAGE\"}\n)\n```\n\nReturn shape (PNG):\n```\n{\n \"status\": \"success\",\n \"content\": [{\"type\":\"image\",\"data\":\"\",\"mimeType\":\"image/png\"}]\n}\n```\n\n## Configuration\n\nThe server can be configured via environment variables or command line arguments:\n\n### Server Settings\n- `MCP_TRANSPORT` - Transport type: `streamable-http` or `stdio` (default: `streamable-http`)\n- `MCP_HOST` - Host address (default: `0.0.0.0`)\n- `MCP_PORT` - Port number (default: `8000`)\n- `LOG_LEVEL` - Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` (default: `INFO`)\n- `MCP_DEBUG` - Enable debug mode: `true` or `false` (default: `false`)\n\n### Chart Settings\n- `CHART_DEFAULT_WIDTH` - Default chart width in pixels (default: `800`)\n- `CHART_DEFAULT_HEIGHT` - Default chart height in pixels (default: `600`)\n- `CHART_DEFAULT_DPI` - Default chart DPI (default: `100`)\n- `CHART_MAX_DATA_POINTS` - Maximum data points per chart (default: `10000`)\n\n### Command Line Usage\n\n**With uvx (recommended):**\n```bash\nuvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --help\n\n# Examples:\nuvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --port 8080 --log-level DEBUG\nuvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --chart-width 1200 --chart-height 800\n```\n\n**Traditional Python:**\n```bash\npython -m src --help\n\n# Examples:\npython -m src --transport streamable-http --host 0.0.0.0 --port 8000\npython -m src --log-level DEBUG --chart-width 1200 --chart-height 800\n```\n\n## Docker\n\nBuild image:\n```\ndocker build -t mcp-plots .\n```\n\nRun container with custom configuration:\n```bash\ndocker run --rm -p 8000:8000 \\\n -e MCP_TRANSPORT=streamable-http \\\n -e MCP_HOST=0.0.0.0 \\\n -e MCP_PORT=8000 \\\n -e LOG_LEVEL=INFO \\\n -e CHART_DEFAULT_WIDTH=1000 \\\n -e CHART_DEFAULT_HEIGHT=700 \\\n -e CHART_DEFAULT_DPI=150 \\\n -e CHART_MAX_DATA_POINTS=5000 \\\n mcp-plots\n```\n\n## Cursor MCP Integration\n\n### Quick Setup for Cursor\n\nThe Plots MCP Server is designed to work seamlessly with Cursor's MCP support. Here's how to integrate it:\n\n#### 1. **Add to Cursor's MCP Configuration**\n\nAdd this to your Cursor MCP configuration file (`~/.cursor/mcp.json` or similar):\n\n```json\n{\n \"mcpServers\": {\n \"plots\": {\n \"command\": \"uvx\",\n \"args\": [\n \"--from\", \n \"git+https://github.com/mr901/mcp-plots.git@main\",\n \"mcp-plots\",\n \"--transport\", \n \"stdio\"\n ],\n \"env\": {\n \"LOG_LEVEL\": \"INFO\",\n \"CHART_DEFAULT_WIDTH\": \"800\",\n \"CHART_DEFAULT_HEIGHT\": \"600\"\n }\n }\n }\n}\n```\n\n#### 2. **Alternative: HTTP Transport**\n\nFor HTTP-based integration:\n\n```json\n{\n \"mcpServers\": {\n \"plots-http\": {\n \"command\": \"uvx\",\n \"args\": [\n \"--from\", \n \"git+https://github.com/mr901/mcp-plots.git@main\", \n \"mcp-plots\",\n \"--transport\", \n \"streamable-http\",\n \"--host\", \n \"127.0.0.1\",\n \"--port\", \n \"8000\"\n ]\n }\n }\n}\n```\n\n#### 3. **Local Development Setup**\n\nFor local development (if you have the code cloned):\n\n```json\n{\n \"mcpServers\": {\n \"plots-dev\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"src\", \"--transport\", \"stdio\"],\n \"cwd\": \"/path/to/mcp-plots\",\n \"env\": {\n \"LOG_LEVEL\": \"DEBUG\"\n }\n }\n }\n}\n```\n\n#### 4. **Verify Integration**\n\nAfter adding the configuration:\n1. **Restart Cursor**\n2. **Check MCP connection** in Cursor's MCP panel\n3. **Test with a simple chart**:\n ```\n Create a bar chart showing sales data: A=100, B=150, C=80\n ```\n\n### **MERMAID-First Approach**\n\nThis server prioritizes **MERMAID output by default** because:\n- ✅ **Renders instantly in Cursor** - No external viewers needed\n- ✅ **Interactive** - Cursor can analyze and discuss the diagrams \n- ✅ **Lightweight** - Fast generation and display\n- ✅ **Scalable** - Vector-based, works at any zoom level\n\n**Chart Types with Native MERMAID Support:**\n- `line`, `bar`, `pie`, `area` → `xychart-beta` format\n- `histogram` → `xychart-beta` with automatic binning \n- `funnel` → Styled flowchart with color gradients\n- `gauge` → Flowchart with color-coded value indicators\n- `sankey` → Flow diagrams with source/target styling\n\n## Available Tools\n\n### `render_chart`\nMain chart generation tool with MERMAID-first approach.\n\n**Parameters:**\n- `chart_type` - Chart type (`line`, `bar`, `pie`, `scatter`, `heatmap`, etc.)\n- `data` - List of data objects\n- `field_map` - Field mappings (`x_field`, `y_field`, `category_field`, etc.)\n- `config_overrides` - Chart configuration overrides\n- `output_format` - Output format (`mermaid` [default], `mcp_image`, `mcp_text`)\n\n**Special Modes:**\n- `chart_type=\"help\"` - Show available chart types and themes\n- `chart_type=\"suggest\"` - Analyze data and suggest field mappings\n\n### `configure_preferences`\nInteractive configuration tool for setting user preferences.\n\n**Parameters:**\n- `output_format` - Default output format (`mermaid`, `mcp_image`, `mcp_text`)\n- `theme` - Default theme (`default`, `dark`, `seaborn`, `minimal`)\n- `chart_width` - Default chart width in pixels\n- `chart_height` - Default chart height in pixels\n- `reset_to_defaults` - Reset all preferences to system defaults\n\n**Features:**\n- **Persistent Settings** - Saved to `~/.plots_mcp_config.json`\n- **Live Preview** - Shows sample chart with current settings\n- **Override Support** - Use `config_overrides` for one-off changes\n\n## Documentation\n\n### Additional Resources\n- **[Complete Documentation](https://github.com/MR901/mcp-plots/blob/main/docs/README.md)** - Technical documentation hub\n- **[Quick Start](https://github.com/MR901/mcp-plots/blob/main/docs/quickstart.md)** - 5-minute setup guide\n- **[Integration Guide](https://github.com/MR901/mcp-plots/blob/main/docs/integration.md)** - MCP client setup and configuration\n- **[API Reference](https://github.com/MR901/mcp-plots/blob/main/docs/api.md)** - Complete tool specifications and examples\n- **[Advanced Guide](https://github.com/MR901/mcp-plots/blob/main/docs/advanced.md)** - Architecture, deployment, and development\n- **[Sample Prompts](https://github.com/MR901/mcp-plots/blob/main/docs/sample-prompts.md)** - Ready-to-use testing examples\n\n### Chart Examples\n\n**Basic Bar Chart:**\n```json\n{\n \"chart_type\": \"bar\",\n \"data\": [\n {\"category\": \"Sales\", \"value\": 120},\n {\"category\": \"Marketing\", \"value\": 80},\n {\"category\": \"Support\", \"value\": 60}\n ],\n \"field_map\": {\n \"category_field\": \"category\", \n \"value_field\": \"value\"\n }\n}\n```\n\n**Time Series Line Chart:**\n```json\n{\n \"chart_type\": \"line\",\n \"data\": [\n {\"date\": \"2024-01\", \"revenue\": 1000},\n {\"date\": \"2024-02\", \"revenue\": 1200},\n {\"date\": \"2024-03\", \"revenue\": 1100}\n ],\n \"field_map\": {\n \"x_field\": \"date\",\n \"y_field\": \"revenue\"\n }\n}\n```\n\n**Funnel Chart:**\n```json\n{\n \"chart_type\": \"funnel\",\n \"data\": [\n {\"stage\": \"Awareness\", \"value\": 1000},\n {\"stage\": \"Interest\", \"value\": 500}, \n {\"stage\": \"Purchase\", \"value\": 100}\n ],\n \"field_map\": {\n \"category_field\": \"stage\",\n \"value_field\": \"value\"\n }\n}\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n- `MCP_TRANSPORT` - Transport type (`streamable-http` | `stdio`)\n- `MCP_HOST` - Host address (default: `0.0.0.0`)\n- `MCP_PORT` - Port number (default: `8000`)\n- `LOG_LEVEL` - Logging level (default: `INFO`)\n- `MCP_DEBUG` - Enable debug mode (`true` | `false`)\n- `CHART_DEFAULT_WIDTH` - Default chart width in pixels (default: `800`)\n- `CHART_DEFAULT_HEIGHT` - Default chart height in pixels (default: `600`)\n- `CHART_DEFAULT_DPI` - Default chart DPI (default: `100`)\n- `CHART_MAX_DATA_POINTS` - Maximum data points per chart (default: `10000`)\n\n### User Preferences\nPersonal preferences are stored in `~/.plots_mcp_config.json`:\n```json\n{\n \"defaults\": {\n \"output_format\": \"mermaid\",\n \"theme\": \"default\",\n \"chart_width\": 800,\n \"chart_height\": 600\n },\n \"user_preferences\": {\n \"output_format\": \"mcp_image\",\n \"theme\": \"dark\"\n }\n}\n```\n\n## 🚀 Advanced Usage\n\n### Custom Themes\nAvailable themes: `default`, `dark`, `seaborn`, `minimal`, `whitegrid`, `darkgrid`, `ticks`\n\n### High-Resolution Charts\n```bash\nuvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots \\\n --chart-width 1920 \\\n --chart-height 1080 \\\n --chart-dpi 300\n```\n\n### Performance Optimization\n- Use `max_data_points` to limit large datasets\n- MERMAID output is fastest for quick visualization\n- PNG output for high-quality static images\n- SVG output for scalable vector graphics\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Issue**: Charts not rendering in Cursor\n- **Solution**: Ensure `output_format=\"mermaid\"` (default)\n- **Check**: MCP server connection in Cursor\n\n**Issue**: `uvx` command not found\n- **Solution**: Install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`\n\n**Issue**: Port already in use\n- **Solution**: Use different port: `--port 8001`\n\n**Issue**: Large datasets slow\n- **Solution**: Sample data or increase `--max-data-points`\n\n### Debug Mode\n```bash\nuvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots \\\n --debug \\\n --log-level DEBUG\n```\n\n## 📝 Notes\n\n- Matplotlib runs headless (Agg backend) in the container\n- For large datasets, sample your data for responsiveness \n- Chart defaults can be overridden per-request via `config_overrides`\n- MERMAID charts render instantly in Cursor for the best user experience\n- User preferences persist across sessions and apply to all charts by default\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_95":96,"_97":98,"_99":100,"_101":102,"_103":-5,"_104":105},"requiredSecrets",[],"tags",[94],"assets",[],"stats",{"_92":81,"_93":81},"ratingAvg","reviewCount","ready-to-use","topics",[94],"license","MIT","language","Python","registryName","io.github.MR901/mcp-plots","homepage","packages",[106],{"_107":108,"_109":21,"_71":110},"registryType","pypi","identifier","0.0.2","ENV",{"_113":114,"_115":116,"_117":118},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]