MCP Server

MCP Server

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.

Canonical install guide: .claude/skills/docs/guides/START_HERE.md. This page is a workflow overview.

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.

Installation modes

Mode	Best for	Install path
Claude Desktop Extension (.mcpb bundle)	Most users; auto-downloads the qsvmcp binary	Double-click the .mcpb from releases
Legacy MCP server (claude_desktop_config.json)	Power users; full control over env vars	Edit Claude Desktop config — see docs/guides/START_HERE.md
Claude Code (Anthropic CLI)	Developers, terminal workflows	Build qsvmcp from source — see CLAUDE_CODE.md
Gemini CLI / other MCP hosts	Multi-client setups	Same as Claude Code — point the client at the qsvmcp binary

Quickest install (Claude Desktop)

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.

Configure (optional)

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).

Tool surface

The MCP server exposes the entire qsv command catalog as MCP tools. Key tools (~60 in total in qsvmcp):

• Inspection: qsv_count, qsv_headers, qsv_sniff, qsv_sample, qsv_slice, qsv_select, qsv_search
• Stats & profiling: qsv_stats, qsv_moarstats, qsv_frequency, qsv_pragmastat, qsv_describegpt
• Transform: qsv_apply, qsv_datefmt, qsv_dedup, qsv_fill, qsv_replace, qsv_sort
• Joins / SQL: qsv_join, qsv_joinp, qsv_sqlp, qsv_pivotp, qsv_scoresql
• Validation: qsv_validate, qsv_schema
• Convert: qsv_to_parquet, qsv_to_xlsx, qsv_excel_export, qsv_jsonl, qsv_tojsonl
• Geospatial: qsv_geocode_suggest, qsv_geocode_reverse
• Web: qsv_fetch, qsv_fetchpost
• Filesystem: qsv_list_files, qsv_set_working_dir, qsv_get_working_dir, qsv_search_tools

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

Deferred loading: Most MCP clients only load the core tools at startup and fetch additional tools on demand. Set QSV_MCP_EXPOSE_ALL_TOOLS=true to expose everything upfront (for clients without deferred-loading support).

Security model

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).

Concurrency & limits

• 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.

Logging & audit

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).

Update checks

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.

Use with Claude Code (CLI)

# 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.

Use with Gemini CLI

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.

End-to-end example

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.

Troubleshooting

Symptom	Fix
.mcpb install fails	Verify Claude Desktop ≥ the version required in the release notes
Permission denied on a file	Add the directory to QSV_MCP_ALLOWED_DIRS
qsv binary not found	Set QSV_MCP_BIN_PATH to the qsvmcp binary path
Operation times out on huge file	Bump QSV_MCP_OPERATION_TIMEOUT_MS (max 30 min)
MCP audit log fills disk	Set QSV_MCP_LOG_LEVEL=error or off

For more, see Troubleshooting.

See also

• .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