# AVA MCP server

> Allows an AI client to load datasets, execute SQL queries, perform natural language data analysis, and generate chart specifications.

- Repository: https://github.com/DoubleCore/mcp-server-ava
- Page: https://hostedmcp.org/servers/doublecore/mcp-server-ava
- Transport: stdio
- Stars: 0
- License: MIT
- Latest version: 0.1.3

## Install

### Claude Code

```sh
claude mcp add mcp-server-ava -- npx -y mcp-server-ava
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mcp-server-ava": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-ava"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "mcp-server-ava": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-ava"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp-server-ava","type":"stdio","command":"npx","args":["-y","mcp-server-ava"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mcp-server-ava": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-ava"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add mcp-server-ava -- npx -y mcp-server-ava
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mcp-server-ava]
command = "npx"
args = ["-y", "mcp-server-ava"]
```

### Gemini CLI

```sh
gemini mcp add -s user mcp-server-ava npx -- -y mcp-server-ava
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcp-server-ava": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-ava"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `AVA_MCP_MAX_ROWS` | no | no |  |
| `OPENAI_API_KEY` | no | no |  |
| `OPENAI_BASE_URL` | no | no |  |
| `OPENAI_MODEL` | no | no |  |

## Tools (8)

- `ava_load_data`: Load a dataset and return its schema. Replaces the previously loaded dataset. Use inline CSV or JSON for small pasted data, or a file path for larger local files.
- `ava_schema`: Return table names, columns, and types for the loaded dataset. (read-only)
- `ava_profile`: Compute column statistics (row count, nulls, distinct, min, max, mean, median) for the dataset. (read-only)
- `ava_query`: Execute one read-only SELECT statement with DuckDB semantics. Aggregate, filter, and sort in SQL so the result stays small. (read-only)
- `ava_analyze`: Ask a question about the loaded dataset. AVA writes and executes the SQL, then summarizes the result. Requires OPENAI_API_KEY (and optionally OPENAI_MODEL / OPENAI_BASE_URL) in the server environment. (read-only)
- `ava_translate`: Translate a question into SQL without running it, so a human can review the statement first. (read-only)
- `ava_suggest`: Suggest questions worth asking about the loaded dataset. Requires a model configuration. (read-only)
- `ava_visualize`: Recommend a chart for rows from ava_query or ava_analyze. Returns a GPT-Vis config, which AVA renders to standalone HTML with the `viz --spec` CLI command. (read-only)

## FAQ

### What file formats can I load with AVA?

You can load inline CSV, JSON, or text, as well as file paths for .csv, .json, .parquet, and .xlsx files.

### Is the SQL execution safe?

Yes, SQL execution is read-only; the engine rejects writes, DDL, and multi-statement scripts.

### How do I render the charts suggested by the server?

The server returns a JSON spec rather than HTML; you must save this spec and use the AVA CLI to render it into an HTML file.

### Do I need an API key to use the server?

An OpenAI-compatible API key is required specifically for model-backed tools like analysis, translation, and visualization.
