datawrapper-mcp: Instructions file for Codex

datawrapper-mcp

MCP server providing tools for creating Datawrapper charts through AI assistants.

Critical: Using This MCP Server

This MCP server IS the Datawrapper integration.

When users ask to create Datawrapper charts:

• Use the create_chart MCP tool from this server
• Use get_chart_schema to explore configuration options
• Use update_chart, publish_chart, and other MCP tools as needed

Do NOT:

• Install the datawrapper Python package
• Use the Datawrapper API directly
• Import from datawrapper import ...
• Run pip install datawrapper

The MCP tools are the ONLY interface for Datawrapper chart operations.

Environment Setup

# Required: Set your Datawrapper API token
export DATAWRAPPER_ACCESS_TOKEN="your-token-here"
# Get token from: https://app.datawrapper.de/account/api-tokens

Build and Test Commands

# Install package in development mode
pip install -e .

# Run the MCP server
datawrapper-mcp

# Run tests
pytest

# Run tests with coverage
pytest --cov=.

# Type checking
mypy server.py config.py utils.py dw_types.py handlers

# Linting
ruff check .

Project Structure

.
├── server.py            # Main MCP server implementation
├── config.py            # Configuration and chart type mappings
├── utils.py             # Utility functions (data conversion, API token)
├── dw_types.py          # TypedDict argument contracts for handlers
└── handlers/            # Handler modules for each operation
    ├── create.py        # Chart creation handler
    ├── update.py        # Chart update handler
    ├── delete.py        # Chart deletion handler
    ├── publish.py       # Chart publishing handler
    ├── export.py        # Chart export handler
    ├── retrieve.py      # Chart retrieval handler
    └── schema.py        # Schema retrieval handler

Available MCP Tools

Tool	Description
create_chart	Create chart with full Pydantic config
get_chart_schema	Get JSON schema for a chart type
get_chart	Retrieve chart info and complete configuration
update_chart	Update chart data or configuration
delete_chart	Delete a chart
publish_chart	Publish chart (only on explicit user request)
export_chart_png	Export as PNG (only on explicit user request)