mcp-server-ava

Model Context Protocol server for AVA. Load a dataset, inspect it, run SQL, ask questions in natural language, and get charts — from Claude Desktop, Cursor, ChatGPT, or any other MCP client.

AVA does the data access, SQL execution, and chart specs; your MCP client's own agent does the reasoning. No AVA CLI or extra API key is needed for deterministic work.

Install

npm install -g mcp-server-ava @antv/ava@beta

@antv/ava v4 is a peer dependency and is still published under the beta tag — install it alongside. Without installing globally: npx -y -p mcp-server-ava -p @antv/ava@beta mcp-server-ava.

Requires Node.js ≥ 22.13.

Related MCP server: duckdb-analytics-mcp

Client configuration

Add the server to your MCP client config. The env block is only needed for the model-backed tools (ava_analyze, ava_translate, ava_suggest, ava_visualize).

Claude Desktop (claude_desktop_config.json) / Cursor (~/.cursor/mcp.json) / most clients:

{
  "mcpServers": {
    "ava": {
      "command": "npx",
      "args": ["-y", "mcp-server-ava"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_MODEL": "gpt-4o-mini",
        "OPENAI_BASE_URL": "https://api.openai.com/v1",
        "AVA_MCP_MAX_ROWS": "200"
      }
    }
  }
}

Any OpenAI-compatible endpoint works — set OPENAI_BASE_URL for Azure, OpenRouter, a local vLLM, or an internal gateway.

Tools

Every tool returns JSON text. Failures (no dataset loaded, invalid SQL, engine errors) come back as MCP error results, so the agent sees the message instead of a dead connection.

Example conversation

You: Load examples/sales.csv and tell me which region sells the most, then chart it.

Agent: calls ava_load_data → ava_query (SELECT region, SUM(sales)…) → ava_visualize, replies "West sells the most at 13 units" and returns chart JSON.

Rendering a returned chart

ava_visualize returns a spec, not HTML. Save the spec and render it with the AVA CLI:

npm install -g @antv/ava            # provides the `ava` binary
npx ava viz --spec @chart.json -o chart.html

Configuration

Safety notes

• One dataset per server process; loading again replaces it. Run separate servers for separate datasets.

• SQL is read-only: writes, DDL, and multi-statement scripts are rejected by the engine.

• Results are truncated to the row cap and flagged with truncated: true.

• Diagnostics go to stderr — stdout is reserved for the MCP protocol.

Development

npm install
npm run build
npm test                              # vitest: in-memory MCP client over the real server
node scripts/smoke.mjs                # end-to-end over stdio against the built binary
OPENAI_API_KEY=... node scripts/smoke.mjs   # also exercises analyze + visualize

License

MIT