Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@mcpx-digital/csv-tools validate ./data/users.csv and require columns id,email with email type"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for local CSV validation and conversion.
Validate CSV structure, check simple schemas, convert CSV↔JSON, sample rows, and find duplicate keys — all on local files.
Privacy: Never uploads user data anywhere. All processing is local.
npx -y @mcpx-digital/csv-toolsRelated MCP server: csv-mcp-server
mcp.json example{
"mcpServers": {
"csv-tools": {
"command": "npx",
"args": ["-y", "@mcpx-digital/csv-tools"]
}
}
}Local clone:
{
"mcpServers": {
"csv-tools": {
"command": "node",
"args": ["/absolute/path/to/csv-tools-mcp/index.js"]
}
}
}Tool | What it does |
| Headers, column counts, duplicate headers |
| Required columns + basic types |
| CSV → JSON records |
| JSON → CSV (optional write to disk) |
| First N rows |
| Duplicate groups by key columns |
“Validate ./data/users.csv”
“Require columns id,email and check email types”
“Convert export.csv to JSON and show 5 sample rows”
“Find duplicate email values in users.csv”
git clone https://github.com/TheoryofShadows/csv-tools-mcp.git
cd csv-tools-mcp
npm install
npm testMIT
Convert a local CSV file to JSON records (returned in tool result). Local files only — never uploads user data anywhere.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to CSV file. | |
| delimiter | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses that output is returned inline in the tool result and that nothing is uploaded anywhere, which is meaningful for a file-processing tool. However it omits error behavior on malformed CSV, size limits, and how the delimiter affects parsing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no wasted preamble. The trailing privacy assurance slightly duplicates the "local" qualifier already stated, but it is brief and arguably reassuring rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Absence of an output schema is mitigated because the description states results are returned in the tool result. For a simple two-parameter converter this is close to adequate, but the undocumented delimiter parameter leaves a real gap in a low-annotation definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%: filePath is documented in the schema, but delimiter has no description anywhere — neither schema nor tool description explains accepted values, defaults, or delimiter detection. The description does not compensate for this gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb (convert) and both source and target resources (CSV file → JSON records), so the transformation direction is unambiguous against siblings like json_to_csv. It does not explicitly reference the inverse tool, but the direction is clear enough to route correctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Local files only" is a scoping constraint rather than usage guidance. There is no explicit when-to-use, when-not, or named alternative (e.g. json_to_csv, validate_csv), so the agent must infer the selection context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find duplicate rows by one or more key columns. Local files only — never uploads user data anywhere.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | ||
| delimiter | No | ||
| keyColumns | Yes | Column name(s) forming the unique key. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It correctly signals a read-only local operation and reassures about privacy ('never uploads user data anywhere'), but says nothing about whether duplicates are removed, returned, or flagged, nor about output format. That is a meaningful gap for an analysis tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero waste, and the core purpose is front-loaded before the locality note. Nothing could be cut without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-param tool with no annotations, no output schema, and low schema coverage, the description leaves unclear what the tool returns (a list of duplicate rows? a count?) and how the delimiter default behaves. The local-only note is useful but not sufficient to make the tool fully callable without inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 33%, so the description is expected to compensate. It adds meaning for keyColumns ('one or more key columns') matching the minItems constraint, but filePath and delimiter remain undocumented beyond the schema types. Partial compensation only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (find) and resource (duplicate rows) qualified by key columns, which is distinct from sibling tools like validate_csv or schema_check. It lacks any explicit differentiation from those siblings, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no conditions, and no mention of alternatives among the CSV manipulation siblings. The only contextual hint is 'Local files only,' which is a constraint rather than usage routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert JSON records (or a local JSON array file) to CSV; optionally write to outputPath. Local files only — never uploads user data anywhere.
| Name | Required | Description | Default |
|---|---|---|---|
| headers | No | ||
| records | No | Inline array of objects (alternative to jsonPath). | |
| jsonPath | No | Path to JSON file (array of objects). | |
| outputPath | No | If set, write CSV to this local path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It helpfully discloses the local-only, no-upload behavior, but says nothing about whether writing to outputPath overwrites existing files, what permissions are needed, or what happens when no outputPath is provided (returned string vs. file write).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with the core action front-loaded and the privacy constraint appended. No wasted words, though it packs multiple ideas into one clause chain.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no annotations and no output schema, the description covers the main conversion flow and the local-only guarantee, but omits the return behavior (CSV string vs. written file), overwrite semantics, and header handling, leaving meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so most parameters are documented in the schema. The description confirms outputPath is optional and the records/jsonPath are alternative input sources, but adds no syntax, format, or header-order detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (convert JSON records/file to CSV) and clarifies input forms (inline records vs. a local JSON array file). It is clear and distinguishes the direction of conversion, though it doesn't explicitly contrast with the csv_to_json sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a useful constraint ('Local files only — never uploads user data anywhere') and notes outputPath is optional, but gives no explicit when-to-use vs. when-not guidance or alternatives relative to siblings like csv_to_json.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the first N data rows from a CSV (default 5, max 100). Local files only — never uploads user data anywhere.
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | Number of rows to sample. | |
| filePath | Yes | ||
| delimiter | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose two useful traits: the default/max row cap and the 'local files only, never uploads' privacy guarantee. However, it says nothing about error behavior, delimiter handling semantics, or what the returned rows look like structurally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the core behavior first and the default/max constraints immediately after. Every clause adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should explain the return shape and edge cases more fully. It adequately conveys the operation and the local-only guarantee but omits delimiter behavior and failure modes, leaving it adequate-but-incomplete for a 3-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only 'n' is documented). The description usefully adds the default (5) and max (100) for n and strongly implies filePath is a local path, but the delimiter parameter is never mentioned in either the schema or the description, leaving a real gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a precise verb+resource+scope ('Return the first N data rows from a CSV'), which clearly separates it from validation/conversion siblings like validate_csv or csv_to_json. It does not explicitly name or contrast with any sibling, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use statement or routing to an alternative tool (e.g., validate_csv for schema checks or csv_to_json for conversion). Usage is only implied by the word 'sample', leaving the agent to infer the preview/inspection scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check required columns and simple column types (string|number|integer|boolean|email|url). Local files only — never uploads user data anywhere.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to CSV file. | |
| delimiter | No | ||
| columnTypes | No | Map of column name → type. | |
| requiredColumns | No | Column names that must exist. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose one meaningful trait: it is local-only and never uploads user data. It does not say whether the tool is read-only, what happens on failure, or how results are reported, so the disclosure is real but thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, no filler, with the core purpose front-loaded and the locality guarantee immediately after. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter tool with no annotations and no output schema, the description covers purpose, type vocabulary and data locality, but leaves the relationship to validate_csv and the shape of the returned report unexplained. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, just under the high-coverage threshold, so the schema does most of the work. The description adds the closed type vocabulary for columnTypes, which is genuinely useful, but says nothing about delimiter behavior or how requiredColumns interacts with the type map.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: checking required columns and column types, and even enumerates the supported type vocabulary. However, it never distinguishes itself from the sibling validate_csv, whose remit plausibly overlaps, so an agent cannot fully disambiguate from the name plus description alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage constraint is 'Local files only', which limits the input domain but says nothing about when to reach for this versus validate_csv or the other CSV siblings. No prerequisites, no when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate CSV structure (headers, consistent column counts, duplicate headers). Local files only — never uploads user data anywhere.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to CSV file. | |
| delimiter | No | Field delimiter (default ','). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does add one meaningful behavioral fact: it operates on local files and never uploads user data, which is genuinely useful trust context. However, it says nothing about whether the operation is read-only, how malformed or unreadable files are handled, or what the validation result looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with zero filler. The capability is front-loaded and the privacy constraint follows immediately, so an agent gets the essentials in the first read.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool this is close to adequate, and the description usefully enumerates the checks performed. But with no annotations and no output schema, the agent is never told what a validation result contains (boolean, error list, line numbers), which is the key thing a caller needs to act on the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both filePath and delimiter are already documented in the schema. The description adds no syntax, format, or encoding detail (e.g. supported delimiters, auto-detection) beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (validate CSV) and enumerates exactly what is validated: headers, consistent column counts, duplicate headers. That is far more than a restatement of the name. It does not, however, distinguish itself from the sibling schema_check, which an agent could plausibly confuse for structural validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance and no routing to alternatives such as schema_check or find_duplicate_keys. The 'Local files only' clause is a scoping constraint rather than a usage rule, and usage must be inferred from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0csv_to_jsonfind_duplicate_keysjson_to_csvsample_rowsschema_checkvalidate_csvScored across 6 tools
Most tools target distinct operations (convert, sample, find duplicates, validate, schema check). However, validate_csv and schema_check overlap somewhat since both assess CSV structure/quality, though they focus on different aspects (structure vs. column requirements/types). The descriptions help distinguish them.
Five tools follow snake_case with clear verb_noun or noun patterns (json_to_csv, csv_to_json, validate_csv, sample_rows, find_duplicate_keys), but schema_check lacks a verb and uses a different construction, introducing minor inconsistency.
Six tools is well-scoped for a CSV utility server. Each tool covers a distinct common CSV task (conversion, sampling, duplication detection, validation, schema checking), earning its place without redundancy.
The surface covers key CSV operations: conversion both ways, sampling, duplicate detection, validation, and schema checking. Minor gaps include a dedicated CSV writing/transformation tool (e.g., filter columns, sort) or a dedicated row/column manipulation tool, but core workflows are well supported.
Open, inspect, filter, edit and convert xlsx and csv files from your AI chat. Processing is local.
Validate JSON, YAML, XML and CSV with exact line/column errors and silent-corruption warnings.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
Dedupe, flatten and clean messy JSON rows (emails, phones, URLs, HTML) in one call, as JSON or CSV.