ChemDataDoctor MCP

An MIT-licensed, independent MCP server for local chemical data cleaning. Repository target: chemaiatlas/chemdatadoctor-mcp.

No account, API key, subscription, hosted database or runtime network connection is needed. All cleaning runs on your computer over stdio. The server makes no outbound requests and includes no telemetry. Installation downloads open-source dependencies; after installation it runs offline. Your MCP client controls what tool inputs and outputs it sends to its model provider. Dataset tools return counts by default; raw records stay in local artifacts.

Install from source

Requires Node.js 22.12+ (Node.js 24 recommended) and npm.

cd chemdatadoctor-mcp
npm ci --ignore-scripts
npm test
npm run build
node dist/cli.js --data-root /absolute/path/to/data

The last command waits for an MCP client on stdin. Start the compiled CLI directly in client configurations; npm startup banners must not enter the protocol stream. Only the standalone repository needs to be checked out. No parent website files are required. This project has not been published to npm or GitHub by this task. When working from a ZIP, extract it and use its directory as the project root.

--data-root is required and must name an existing directory. Input file paths are relative to that root, or absolute paths within it. Traversal and resolved symlink escapes are rejected. --output-root is optional; its default is <data-root>/.chemdatadoctor-output. Output directories are created only by clean_dataset. Use a dedicated data directory containing only intended inputs.

Related MCP server: datapact

MCP client configuration

Replace all example paths, including the path to your Node executable if your client does not inherit your shell's PATH. No environment variables are required.

Claude Code

claude mcp add --transport stdio chemdatadoctor -- node /absolute/path/to/chemdatadoctor-mcp/dist/cli.js --data-root /absolute/path/to/data

See the official Claude Code MCP documentation.

Claude Desktop and clients accepting mcpServers JSON

Merge this entry into your client's MCP configuration:

{
  "mcpServers": {
    "chemdatadoctor": {
      "command": "node",
      "args": [
        "/absolute/path/to/chemdatadoctor-mcp/dist/cli.js",
        "--data-root", "/absolute/path/to/data"
      ]
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.chemdatadoctor]
command = "node"
args = ["/absolute/path/to/chemdatadoctor-mcp/dist/cli.js", "--data-root", "/absolute/path/to/data"]

The command/args configuration follows the official OpenAI MCP documentation. Configuration files with placeholders are included in examples/.

Tools

Every tool advertises input and output JSON Schemas through tools/list. The exact generated schemas are in docs/tool-schemas.json. Unexpected fields are rejected. Each inline cell/string is limited to 10,000 characters; total tool arguments are limited to 1 MiB after schema validation.

Dataset options:

CSV/TSV and XLS/XLSX are supported. JSON accepts an array of row arrays, or an array of flat objects. Object arrays require header=true; columns follow the union of object keys in first-seen order. Null and absent cells become empty strings. Nested objects/arrays are rejected. JSON original means parsed cell values (not byte-for-byte JSON serialization); the source file is always retained.

Examples

Validate and safely normalize identifiers:

{"values":["67-64-1","CAS: 67–64–1","67-64-2","67641"],"applyFixes":true}

Call validate_cas with this input. The labeled identifier is normalized to 67-64-1. The wrong checksum and unseparated digits remain unchanged. The valid flag means that the whole identifier has valid format/checksum, allowing a safe formatting suggestion; it never means registered or matched to a substance.

Inspect a workbook without changing anything:

{"path":"inventory.xlsx","sheetIndex":0,"columns":{"cas":0,"name":1,"formula":2}}

Call quality_report first, then call clean_dataset with applyFixes=true if you want local cleaned copies. The result is:

{
  "ok": true,
  "data": {
    "summary": {
      "totalRows": 4,
      "changedRows": 1,
      "duplicateRows": 1,
      "findings": {"error":2,"warning":2,"automatic_fix":2,"unverifiable":13},
      "rowsByCategory": {"error":1,"warning":2,"automatic_fix":1,"unverifiable":4},
      "issuesByCode": {"PREFIX":1,"NAME_WHITESPACE":1,"CAS_IDENTITY_UNVERIFIED":4,"NAME_IDENTITY_UNVERIFIED":4,"FORMULA_PLAUSIBILITY_UNVERIFIED":4,"DUPLICATE":1,"CHECKSUM":1,"FORMULA_SYNTAX":1,"FORMAT":1,"UNSUPPORTED_NOTATION":1}
    },
    "artifacts": {
      "results":"/data/.chemdatadoctor-output/run-unique/results.json",
      "report":"/data/.chemdatadoctor-output/run-unique/report.json",
      "csv":"/data/.chemdatadoctor-output/run-unique/cleaned.csv",
      "excel":"/data/.chemdatadoctor-output/run-unique/cleaned.xlsx"
    },
    "samples": []
  }
}

The numbers above illustrate the structure; counts depend on input. Each run creates a unique directory, never overwrites an existing file and never removes duplicate rows. results.json contains original and cleaned cells, source row numbers (one-based, including the header), suggestions and all findings. report.json contains counts only. CSV exports prefix potentially executable formula strings with an apostrophe; JSON retains their exact text. XLSX exports write strings as text and do not execute or propagate input formulas. Original Excel formulas/macros, formatting and workbook metadata are not preserved in the cleaned workbook; the input file remains untouched. Exported CSV/XLSX include cleaned cells; diagnostic annotations live in JSON, avoiding column collisions.

For an automation example using the official SDK without an LLM or credentials:

node examples/workflow.mjs /absolute/path/to/data inventory.csv

Findings, errors and limits

Findings distinguish error, warning, automatic_fix and unverifiable. Multiple categories may apply to the same row. Summary findings counts events; rowsByCategory counts affected rows; neither is an exclusive partition. An invalid chemical cell is a successful tool execution with an error finding. A failed operation returns isError=true and { "ok":false,"error":{"code": "...","message":"..."} }. Schema-invalid calls are rejected by the SDK and may have text-only errors. Error codes and recovery are documented in docs/ERRORS.md.

Files are limited to 20 MiB, 50,000 data rows, 200 columns, 2,000,000 cells across all sheets and 100 sheets. A file cell may contain at most 10,000 characters. ZIP metadata guards limit expanded size to 100 MiB and per-entry size to 50 MiB, with a maximum compression ratio of 1000. Inputs are bounded and read into memory; this version is not an unbounded streaming reader. Split larger inputs into separate files. Cross-chunk duplicate detection is not shared across calls; to find all duplicates, submit one file within the limits. Nothing is silently truncated. File paths keep complete datasets out of model tool arguments and responses. Optional samples contain metadata only.

CAS checks do not establish registration or substance identity. Names receive no synonym resolution, translation or systematic naming. Formula grammar supports all 118 element symbols, positive integer counts, nested ()/[] groups and hydrates such as CuSO4·5H2O. Charges, explicit isotopes, variables, polymer notation, Unicode subscripts and whitespace are unverifiable. Unknown symbols, unbalanced/empty groups and zero counts are errors. Nesting is limited to 16, individual counts to 1,000,000 and element totals to 1,000,000,000. Formula syntax does not validate bonding, plausibility, CAS/name correspondence or identity.

The root boundary is an application safeguard, not an OS sandbox against a different local process racing filesystem changes. Output artifacts contain user data; retain or delete them according to your own policy. Partial output can remain after disk/permission failures; the source is still unchanged.

Development and release preparation

npm test
npm run schemas
npm run licenses
npm run check:release
npm audit --omit=dev
npm pack --dry-run

Tests cover core regressions, abnormal/boundary inputs, real stdio negotiation, tool discovery, all tool schemas and results, path safety, source preservation, formula-safe exports and calls with network entry points disabled. CI is configured for Node 22/24 on Linux, macOS and Windows. Local verification does not establish that every native client or every OS has been tested.

The source audit and architecture records reuse decisions and the implementation plan. Release instructions explain how to publish only this standalone tree after owner review. Source and third-party licenses are included; dependency versions and integrity hashes are locked. No website operations, internal configuration or hosted data integrations are included. No push or publication is performed by these commands.

License

First-party code: MIT. Reused cleaning core was explicitly authorized by the original repository owner. Dependencies retain their respective licenses; see THIRD_PARTY_NOTICES.md and third-party-licenses/.