Invoice Query MCP Server

Portfolio showcase only. All customers and invoices are fictional sample data. This is not a production product and does not represent a real client engagement.

TypeScript Model Context Protocol (MCP) server that turns a sample invoice CSV into agent-ready tools (list_invoices, get_invoice, invoice_summary, overdue_invoices). Built for Claude Desktop / MCP clients with Zod-validated inputs, Vitest coverage, and a reproducible demo transcript. Shows how to package small, useful data tools for AI agents without dumping whole spreadsheets into the prompt.

Problem

Agents and chat tools often need structured access to tabular finance data (open invoices, overdue balances, customer lookups) without stuffing an entire spreadsheet into the context window.

Related MCP server: Invoice-MCP

Solution

A focused MCP server that loads a sample invoice CSV and exposes four tools:

Stack

• TypeScript / Node.js

• @modelcontextprotocol/sdk (stdio transport)

• Zod for tool input schemas

• csv-parse for CSV loading

• Vitest for unit tests

Quick start

npm install
npm test
npm run build
npm run demo          # writes demo/transcript.txt
npm start             # stdio MCP server (for Claude Desktop / MCP clients)

Claude Desktop config snippet

{
  "mcpServers": {
    "invoice-query": {
      "command": "node",
      "args": ["/absolute/path/to/invoice-query-mcp/dist/src/server.js"]
    }
  }
}

Optional: set INVOICE_CSV_PATH to point at a different CSV with the same columns.

Sample data

See data/sample-invoices.csv — twelve fictional local-business invoices used only for demos.

License

MIT © John Gantz