Allows an AI client to load datasets, execute SQL queries, perform natural language data analysis, and generate chart specifications.
Also known as DoubleCore/mcp-server-ava, mcp-server-ava
- Stars
- 0
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- 0.1.3
- Last commit
- Nov 13, 2026
- License
- MIT
What is AVA MCP?
AVA allows an AI client to load datasets, execute SQL queries, perform natural language data analysis, and generate chart specifications. It exposes 8 tools, such as ava_load_data, ava_schema, ava_profile.
Summary generated from the project's README
About AVA MCP server
Analyzing datasets and generating visual chart specifications from within an AI client is what AVA enables. This server allows developers to load various file formats including CSV, JSON, Parquet, and Excel files to perform data inspection and complex querying. It functions as a bridge between your data and reasoning agents in clients like Claude Desktop or Cursor, handling the heavy lifting of SQL execution and data profiling.
Users can interact with their data using natural language through model-backed tools that require an OpenAI-compatible API key. While the server handles the data access and SQL generation, the reasoning remains with your chosen client. The system uses DuckDB semantics for read-only queries and includes a safety cap on result sizes via the AVA_MCP_MAX_ROWS setting. For visual tasks, the server provides JSON specifications that can be rendered into HTML using the AVA CLI.
What you can do with it
- 1Natural language data interrogationAsk questions about your loaded dataset in plain English to receive a summarized answer and executed SQL.
- 2Automated data profilingQuickly inspect a dataset to find row counts, null values, and statistical distributions like mean or median.
- 3Visual data representationGenerate chart specifications from previous query results to visualize trends and distributions.
- 4SQL translation and reviewConvert natural language requests into raw SQL statements for manual inspection without executing them.
Written from the project's README. Every use case is checked against a quote from it.
How to install AVA MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall AVA MCP in Claude Code
$ claude mcp add mcp-server-ava -- npx -y mcp-server-avaInstall AVA MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server-ava": {
"command": "npx",
"args": [
"-y",
"mcp-server-ava"
]
}
}
}Install AVA MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server-ava": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-server-ava"
]
}
}
}Install AVA MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server-ava","type":"stdio","command":"npx","args":["-y","mcp-server-ava"]}'Install AVA MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server-ava": {
"command": "npx",
"args": [
"-y",
"mcp-server-ava"
]
}
}
}Install AVA MCP in Codex
$ codex mcp add mcp-server-ava -- npx -y mcp-server-avaInstall AVA MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server-ava] command = "npx" args = ["-y", "mcp-server-ava"]
Install AVA MCP in Gemini CLI
$ gemini mcp add -s user mcp-server-ava npx -- -y mcp-server-avaInstall AVA MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server-ava": {
"command": "npx",
"args": [
"-y",
"mcp-server-ava"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for mcp-server-ava 0.1.3 in an isolated container with no network and no keys. It answered and listed 8 tools.
AVA MCP tools 8
Read from the server with tools/listava_load_dataActionLoad 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_schemaRead-onlyReturn table names, columns, and types for the loaded dataset.
ava_profileRead-onlyCompute column statistics (row count, nulls, distinct, min, max, mean, median) for the dataset.
ava_queryRead-onlyExecute one read-only SELECT statement with DuckDB semantics. Aggregate, filter, and sort in SQL so the result stays small.
ava_analyzeRead-onlyAsk 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.
ava_translateRead-onlyTranslate a question into SQL without running it, so a human can review the statement first.
ava_suggestRead-onlySuggest questions worth asking about the loaded dataset. Requires a model configuration.
ava_visualizeRead-onlyRecommend 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.
Configuration
AVA_MCP_MAX_ROWSOPENAI_API_KEYOPENAI_BASE_URLOPENAI_MODEL
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledoublecore/mcp-server-ava is public and reachablegithub.com/doublecore/mcp-server-ava ↗Pass
- Package names this repository as its sourcemcp-server-ava names doublecore/mcp-server-ava as sourcenpmjs.com/package/mcp-server-ava ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for mcp-server-avanpmjs.com/package/mcp-server-ava/v/0.1.3#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/doublecore/mcp-server-ava ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from mcp-server-avaPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcp-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
@antv/ava v4 is a peer dependency — install it alongside. Without installing globally: npx -y -p mcp-server-ava -p @antv/ava mcp-server-ava.
Requires Node.js ≥ 22.13.
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
| Tool | What it does | Needs a model |
|---|---|---|
ava_load_data |
Load inline CSV/JSON/text or a file path (.csv, .json, .parquet, .xlsx). Replaces the current dataset and returns the schema. |
only for text |
ava_schema |
Table names, columns, and types. | no |
ava_profile |
Row count, nulls, distinct, min/max/mean/median per column. | no |
ava_query |
One read-only SQL statement with DuckDB semantics; results capped at AVA_MCP_MAX_ROWS. |
no |
ava_analyze |
Natural-language question → AVA writes SQL, executes it, and summarizes the answer. | yes |
ava_translate |
Natural-language question → SQL, without executing it, so a human can review it. | yes |
ava_suggest |
Suggest questions worth asking about the loaded dataset. | yes |
ava_visualize |
Recommend a chart for rows from a previous call; returns GPT-Vis JSON. | yes |
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.csvand 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
| Env var | Default | Notes |
|---|---|---|
OPENAI_API_KEY |
— | Enables the model-backed tools. Without it they return a clear error. |
OPENAI_MODEL |
gpt-4o-mini |
Any chat model your endpoint exposes. |
OPENAI_BASE_URL |
OpenAI | Point at an OpenAI-compatible gateway. |
AVA_MCP_MAX_ROWS |
200 |
Hard cap per query / analyze result. Truncation is reported in the payload. |
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
Publishing (npm trusted publishing / OIDC)
Releases are published through GitHub Actions with npm provenance — no NPM_TOKEN secret is stored. The workflow (.github/workflows/publish.yml) only runs on a version tag (v*.*.*) or a manual workflow_dispatch run, gives itself contents: read + id-token: write, then runs npm ci → typecheck → build → test → npm pack --dry-run → npm publish --provenance --access public. It uses Node 24 and npm 11.21.2 (Trusted Publishing requires Node ≥ 22.14.0 and npm ≥ 11.5.1), disables release-build caching, and requires a tag to exactly match v + the package.json version.
One-time npm bootstrap and trust
npm only exposes Trusted Publisher settings for a package that already exists; it has no pending-publisher flow for a never-published name. An npm owner must therefore bootstrap a new package through npm's authenticated staging flow (npm stage publish --access public) and approve that initial release with 2FA. Do not dispatch this workflow to claim an unknown package name. After bootstrapping, increment the version so the first OIDC release does not try to republish the bootstrap version.
Once the package exists, configure the trusted publisher on npmjs.com:
- Open Packages → mcp-server-ava → Settings → Trusted publishing and select GitHub Actions.
- Add a trusted publisher entry with:
- Organization or user:
DoubleCore - Repository:
mcp-server-ava - Workflow filename:
publish.yml(filename only, not.github/workflows/publish.yml) - Environment: leave empty — the workflow defines no GitHub environment
- Allowed actions: explicitly allow
npm publish; the defaultnpm stage publishpermission alone cannot authorize this workflow's direct publish command
- Organization or user:
- Save the entry and complete its first successful publish within two days, before the unvalidated configuration expires. The npm account must own the package and have 2FA enabled.
To cut an OIDC release, bump the version and push the resulting commit and tag:
npm version patch # or minor / major
git push --follow-tags
The workflow then builds and tests before publishing with a public provenance statement. mcp-server-ava is a public, unscoped package, hence --access public. Verify the result with npm view mcp-server-ava version; a successful workflow alone is not proof of a Registry submission.
Publishing (official MCP Registry / GitHub OIDC)
server.json names this server io.github.DoubleCore/mcp-server-ava and currently maps version 0.1.3 to the mcp-server-ava@0.1.3 npm artifact. The GitHub OIDC namespace and npm mcpName comparison are case-sensitive, so this exact capitalization is required. Once that artifact is published with the same mcpName, updating Registry metadata at this version does not require another npm version bump or npm publish.
The independent .github/workflows/publish-mcp.yml uses GitHub OIDC with no npm credentials and no npm publish step. It checks that a manual run targets main, that a tag matches the package version and points to a commit merged into main, and that package.json, package-lock.json, server.json, and the published npm mcpName agree. It then runs the project checks and uses the pinned mcp-publisher v1.8.9 release only after verifying its Sigstore bundle with cosign.
For a metadata-only release of the current version, push the commits to main, confirm that npm view mcp-server-ava@0.1.3 mcpName returns the name above, then dispatch Publish to MCP Registry on main:
gh workflow run publish-mcp.yml --ref main
Version tags also trigger this workflow alongside the separate npm release workflow. It never waits for or republishes npm: if a tag run starts before the new npm artifact is visible, let it fail safely and rerun only the MCP workflow after the npm OIDC release succeeds. For a future package version, update package.json, both lockfile root versions, and server.json together; do not reuse an already-published npm version.
A successful workflow is not treated as proof of inclusion. Verify the actual Registry API response instead:
curl 'https://registry.modelcontextprotocol.io/v0.1/servers?search=mcp-server-ava'
License
MIT
AVA MCP questions
How do I add AVA MCP to Claude Code?
Run claude mcp add mcp-server-ava -- npx -y mcp-server-ava in your terminal. Add --scope user to make it available in every project.
How do I add AVA MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does AVA MCP provide?
It exposes 8 tools, including ava_load_data, ava_schema, ava_profile, ava_query, ava_analyze.
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.