MCP server (AI assistants)

The Vectro MCP server lets an AI assistant (Claude Code, Claude Desktop, or any client of the Model Context Protocol) analyse data files on your machine. The assistant loads a file, looks at its columns, and asks Vectro for filters, group-bys, SQL and similarity searches; Vectro answers on every core and sends back small results, not the raw rows. The data never leaves your machine unless the answers do.

The server comes with the vectrojs package as the vectro-mcp command and needs no other dependencies. It is experimental: its tools may change.

Install in Claude Code

claude mcp add vectro -- npx -y -p vectrojs vectro-mcp --root ~/data

Or, with the package installed globally (npm install -g vectrojs):

claude mcp add vectro -- vectro-mcp --root ~/data

--root is the folder the assistant may read; it defaults to the folder the server starts in. Then ask a question in Claude Code, such as “Which region had the most revenue in orders.csv last month?”, and it calls the tools below.

Install in Claude Desktop

Add the server to claude_desktop_config.json (Settings > Developer > Edit Config) and restart Claude Desktop:

{
  "mcpServers": {
    "vectro": {
      "command": "npx",
      "args": ["-y", "-p", "vectrojs", "vectro-mcp", "--root", "/Users/you/data"]
    }
  }
}

Use an absolute path for --root: the config file is not read by a shell, so ~ is not expanded. If Claude Desktop can’t find npx, point command at node and the server file directly:

{
  "mcpServers": {
    "vectro": {
      "command": "/usr/local/bin/node",
      "args": ["/path/to/node_modules/vectrojs/mcp/server.mjs", "--root", "/Users/you/data"]
    }
  }
}

Other MCP clients take the same command and arguments. The server speaks MCP over stdio (JSON-RPC 2.0, one message per line), protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.

Tools

Tool	What it does
load_file	loads a CSV, TSV, JSON-lines, Arrow / Feather file, or opens a .vectro dataset on disk, as a named table; returns its columns, their kinds and a few sample rows
list_tables	the loaded tables with their row counts and columns
describe_table	per column: min, max, mean and missing count for numbers; the number of distinct labels and the most common ones for categories; the date range for dates
query	filter, group_by, aggregates, sort and limit on one table, in Vectro’s expression language
sql	one SQL SELECT over the loaded tables, by name
search_similar	for JSON-lines files with an embedding field: the k rows most similar (cosine) to a given row or vector, with an optional filter
add_column	a computed column, such as revenue = price * qty * (1 - discount)
drop_table	unloads a table and frees its memory

Text columns load as categories, so they can be filtered and grouped. A JSON-lines file whose objects have an array of numbers (an embedding) also gets a vector index, which search_similar uses.

Answers come back as JSON with ms, the time Vectro took. Row results are capped: 50 rows by default and at most 500, with the total count (matching_rows, groups or rows_in_answer) so the assistant knows when there are more. Mistakes come back as tool errors the assistant can read and fix, such as an unknown column or a table that isn’t loaded.

What the assistant sends

A query call and its answer look like this:

{ "table": "orders", "filter": "price > 5", "group_by": "region", "aggregates": { "total": "sum(price)", "n": "count()" }, "sort": "-total" }

{ "groups": 2, "returned": 2, "rows": [{ "region": "US", "total": 20, "n": 1 }, { "region": "EU", "total": 10, "n": 1 }], "ms": 2.9 }

You can try the server without a client by writing JSON-RPC lines to it:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"load_file","arguments":{"path":"orders.csv"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sql","arguments":{"query":"SELECT region, SUM(price) AS total FROM orders GROUP BY region"}}}' \
  | npx -y -p vectrojs vectro-mcp --root ~/data

Safety

• The assistant can only read files under --root. Paths that lead outside it, including through symbolic links, are refused.
• Its filters and formulas are Vectro’s small expression language, with no eval: no code runs, whatever the assistant writes.
• Nothing is written: tables live in the server’s memory, and .vectro datasets are opened read-only.
• Files other than datasets must be under 2 GB; convert bigger ones to a .vectro dataset first (engine.csvToDataset).

The full tool schemas are in the MCP tools reference.