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

# Prepare the checkout and install all dependency groups
make bootstrap

# Run the MCP server
uv run datawrapper-mcp

# Run tests
make test

# Run tests with a coverage report
make coverage

# Fast, non-mutating checks (Ruff lint/format, ty, Deptry, Zizmor)
make check

# Full local verification suite (check + test + manifest + build)
make verify

See make help for the complete list of available commands.

Project Structure

datawrapper_mcp/
├── __init__.py          # Package initialization
├── server.py            # Main MCP server implementation
├── config.py            # Configuration and chart type mappings
├── utils.py             # Utility functions (data conversion, API token)
└── 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