Tier: Intermediate

The qsv MCP Server exposes qsv as a Model Context Protocol server. Any MCP-aware client — Claude Desktop, Claude Code, Gemini CLI, or any future MCP host — can ask qsv to read, profile, transform, and query CSV / Parquet / Excel / JSONL files on your machine, without uploading anything.

The MCP server is the backend that the Claude Cowork Plugin and the qsv MCP integration in Claude Code sit on top of. You can use the MCP server without the Cowork plugin — that just gives you raw tool access from any MCP client.

1. Download the qsv-mcp-server-<version>.mcpb file from releases.
2. Double-click it. Claude Desktop opens.
3. Click Install → Install again to confirm.
4. The .mcpb bundle auto-downloads the matching qsvmcp binary — no manual binary install needed.
5. Restart Claude Desktop. Ask: "List data files in my Downloads folder." If it returns a list, the MCP server is working.

Open Claude Desktop → Settings → Extensions → qsv. Sensible defaults work for most users. Common adjustments:

• Working Directory — where qsv looks for files by default (default: $HOME/Downloads)
• Allowed Directories — additional folders the server may access (security-critical)
• qsv Binary Path — auto-detected; only set if you have a custom build
• Operation Timeout — 10 minutes by default; bump for slow operations on huge files

See Environment Variables → MCP server for the full list (QSV_MCP_* namespace).

The qsvmcp binary carries 70 of qsv 24.0.0's 80 commands (see Binary Variants), of which 57 are exposed as skill-based MCP tools optimized for agent workflows.

Neither get nor fetch/fetchpost is present in qsvmcp at all — an agent that needs to pull a remote file should be handed a local path, or an http(s):///ckan:// URL that the surviving schemes can resolve. Key tools:

Two naming conventions coexist, and they are not interchangeable:

• Skill-based tools — one per covered command, named qsv-<command> with a hyphen (qsv-stats, qsv-joinp, qsv-readstat). A command's subcommands are an argument, not separate tools: to, geocode and excel each get one tool whose subcommand arg carries the valid values.
• Server tools — the MCP server's own, named qsv_<name> with an underscore (qsv_list_files, qsv_set_working_dir, qsv_get_working_dir, qsv_search_tools, qsv_browse_directory, qsv_help, qsv_version, qsv_config).

The skill-based tools by area:

The MCP host enumerates these tools and presents them to the LLM for invocation.

The MCP server enforces directory access controls:

• Working directory — QSV_MCP_WORKING_DIR (default $HOME/Downloads). Templates supported: ${HOME}, ${DOWNLOADS}, ${DOCUMENTS}, ${PWD}, etc.
• Allowed directories — QSV_MCP_ALLOWED_DIRS (colon-separated on Unix, semicolon on Windows). Additional read/write locations.

Any file access outside the working directory + allowed directories is denied. This is a defense-in-depth layer on top of OS-level permissions.

For Claude Desktop Extension mode, an additional flag MCPB_EXTENSION_MODE=true enforces stricter checks (qsv binary must be fully qualified, version must be ≥ 17.0.0).

• Operation timeout: QSV_MCP_OPERATION_TIMEOUT_MS (default 600,000 ms = 10 min, max 30 min).
• Max concurrent operations: QSV_MCP_MAX_CONCURRENT_OPERATIONS (default 3 in plugin mode, 1 in extension mode).
• Concurrency-wait timeout: QSV_MCP_CONCURRENCY_WAIT_TIMEOUT_MS (default 2 min).
• Max output size: QSV_MCP_MAX_OUTPUT_SIZE (default 50 MB). Bigger outputs auto-saved to disk.
• Max files per directory listing: QSV_MCP_MAX_FILES_PER_LISTING (default 1000).

See Environment Variables → MCP server for the complete list.

Two separate logs:

• Tool audit log — qsvmcp.log. Records every tool invocation (request + response). Controlled by QSV_MCP_LOG_LEVEL (info / error / off; default info).
• Binary log — qsv_rCURRENT.log. Standard qsv runtime log. Controlled by QSV_LOG_LEVEL.

Audit logs land in QSV_LOG_DIR (default: directory where the binary was started).

The MCP server checks for new qsv releases at startup unless you disable it:

export QSV_MCP_CHECK_UPDATES_ON_STARTUP=false

When QSV_MCP_AUTO_REGENERATE_SKILLS=true, the server auto-regenerates skill definitions on version change via qsv --update-mcp-skills.

# 1. Install qsvmcp
cargo install qsv --locked --bin qsvmcp -F qsvmcp
# or download a prebuilt binary

# 2. Tell Claude Code about it (~/.claude/settings.json or similar)
#    Add an MCP server entry pointing at the qsvmcp binary.

See CLAUDE_CODE.md for the full Claude Code setup.

Same shape as Claude Code: install qsvmcp, register it as an MCP server in your Gemini CLI config. The QSV_MCP_PLUGIN_MODE=true env var relaxes directory checks since Gemini CLI provides its own filesystem isolation.

User: Profile the file ~/Downloads/customers.csv and tell me about the
      most-common values per column.

Claude: [calls qsv_stats with cardinality + infer-dates]
        [calls qsv_frequency with --limit 10 --json]
        [synthesizes results into narrative]

        Your file has 50,000 rows and 12 columns. The most variable
        column is "city" with 8,402 distinct values; "state" has only
        50 (all US states); "signup_date" spans 2018-01-01 to 2024-...
        ...

All file access stayed on your machine; only stats + frequency summaries went to Claude as LLM context.

Concrete demonstrations of MCP-driven civic analysis — published in the People's API Demos showcase:

• Pittsburgh Parking Reform Analysis — Claude, driven by the qsv MCP Server and the US Census MCP Server, FAIRifies municipal parking data and synthesizes a policy analysis. The "pure MCP" demo: no Cowork plugin involved — just MCP tool calls.

For demos that build the Cowork plugin on top of the MCP server (NYC Snow, NYC Housing), see Claude Cowork Plugin → Real-world demos.

Browse the full showcase at https://dathere.github.io/peoples-api-demos/.

For more, see Troubleshooting.

• .claude/skills/docs/guides/START_HERE.md — canonical install guide
• .claude/skills/docs/guides/CLAUDE_CODE.md — Claude Code setup
• .claude/skills/README-MCP.md — MCP server architecture
• Claude Cowork Plugin — domain skills on top of the MCP server
• Environment Variables → MCP server
• Binary Variants → qsvmcp — what's in the qsvmcp build
• Model Context Protocol spec
• Discussions: Why MCP Server?
• Integrations