Let an agent read your XML documents

@sezzlee/xml-mcp gives an agent read-only access to the XML files in one folder, and to nothing outside it. It has no tool that writes, so a document is never modified.

You need Node.js 22 or later.

1. Pick a folder

Everything under the folder is readable, subfolders included, so pick the narrowest one that holds the documents the agent needs. To follow along, create one and save orders.xml into it: six orders in the namespace urn:example:orders, each with a payment in a second namespace, urn:example:payments. One order has no region and one has no payment, as real exports do.

mkdir -p ~/sezzlee-xml

2. Add the server to your client

Pass the folder as an absolute path. A JSON configuration is not read by a shell, so ~ is not expanded there.

claude mcp add xml -- npx -y @sezzlee/xml-mcp /Users/you/sezzlee-xml

Claude Desktop reads claude_desktop_config.json (Settings → Developer → Edit Config, then restart). Cursor reads .cursor/mcp.json in the project or ~/.cursor/mcp.json. VS Code reads .vscode/mcp.json. Any other client that starts a stdio server works with the command npx and the arguments -y, @sezzlee/xml-mcp and the folder.

3. Ask

Ask the agent: How much was paid per order status in orders.xml?

The agent looks at the document first, then has the server group the orders by status and add up the payments. It gets three lines back instead of six records, and the answer is 2,570 for shipped orders. On a document with fifty thousand records the answer is the same size.

See what the agent receives

The recipes call the tools the way an agent does, through the MCP Inspector, so you can see each answer exactly. They need the server installed once and jq:

npm install -g @sezzlee/xml-mcp

Define this helper in your shell; it reads ~/sezzlee-xml:

xml() {
  npx -y @modelcontextprotocol/inspector --cli sezzlee-xml ~/sezzlee-xml \
    --method tools/call --tool-name "$@" | jq '.content[0].text | fromjson'
}

Name the repeated element once: every order child of orders is one record.

ORDERS='{"ancestors":[{"namespaceUri":"urn:example:orders","localName":"orders"}],"name":{"namespaceUri":"urn:example:orders","localName":"order"}}'

This is the call behind the answer above. Adding up turns text into numbers, which the server does only when numericMode says so:

xml aggregate_document --tool-arg filePath=orders.xml "itemAddress=$ORDERS" \
  'columns=[{"label":"status","value":{"from":"attribute","namespaceUri":"","localName":"status"}},{"label":"paid","name":{"namespaceUri":"urn:example:payments","localName":"payment"}}]' \
  'groupBy=["status"]' 'metrics=[{"fn":"count"},{"fn":"sum","column":"paid"}]' \
  numericMode=binary64 \
  | jq -c '.groups[] | {status: .key[0].value, orders: .metrics[0].value, paid: .metrics[1].value, counted: .metrics[1].counted}'

{"status":"cancelled","orders":1,"paid":0,"counted":0}
{"status":"pending","orders":1,"paid":610,"counted":1}
{"status":"shipped","orders":4,"paid":2570,"counted":4}

The cancelled order has no payment, so its total is 0 with counted: 0. That is different from a payment of zero.

What it can read

• Structure first: the document element, every namespace with a stable alias, and which elements repeat and how often.
• Records as rows: a repeated element becomes a table with named columns, and every cell says whether its value was present, empty, missing or found more than once.
• Answers instead of pages: counts, distinct values, sums and averages per group.
• XPath 1.0, evaluated exactly as written, and literal search over text and attribute values.
• Any part of the tree in document order, as flat records that page without gaps.

It reads .xml, .xsd, .xhtml, .svg, .csproj, .props, .targets, .config and .resx files. Values come back as the exact text in the file. A document over 8 MB is read one record at a time, and a DOCTYPE is refused before anything is parsed.