Docs/MCP / AI Agents
Guides

MCP / AI Agents

Make ReceiptConverter natively available to Claude, Cursor, or any Model Context Protocol (MCP) client. Your AI agent can scan receipts on demand without writing custom glue code every time.

What is MCP? The Model Context Protocol is an open standard by Anthropic that lets AI models call tools defined by third-party servers. Claude Desktop, Cursor, and other MCP clients can discover and call your tools automatically.

Auto-discovery via OpenAPI

ReceiptConverter publishes a machine-readable OpenAPI 3.0 spec. Tools like LangChain, AutoGPT, and LlamaIndex can import this URL to automatically generate a working integration — no manual setup.

# LangChain — load ReceiptConverter as a toolkit
from langchain_community.agent_toolkits.openapi import planner
from langchain_community.utilities import RequestsWrapper
import yaml, requests

spec_url = "https://receiptconverter.com/api/v1/openapi.json"
raw_spec = requests.get(spec_url).json()

headers = {"Authorization": "Bearer sk_live_your_key"}
requests_wrapper = RequestsWrapper(headers=headers)

agent = planner.create_openapi_agent(raw_spec, requests_wrapper, llm)
result = agent.run("Parse this receipt image: https://example.com/lunch.jpg")

Official npm package — zero setup

Install the official receiptconverter-mcp package. No code required — just drop in your API key.

# No install needed — npx downloads it automatically
npx receiptconverter-mcp

The server exposes two tools your AI can call:

convert_receiptParse a receipt or invoice from a URL or local file path. Returns vendor, date, total, line items, taxes, tip, currency, and category.
check_usageCheck remaining conversions and plan limits for your API key.

Connect to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "receiptconverter": {
      "command": "npx",
      "args": ["receiptconverter-mcp"],
      "env": {
        "RECEIPTCONVERTER_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You can now ask: "Parse this receipt for me: https://example.com/lunch.jpg" and Claude will call the tool automatically.

Connect to Cursor

In Cursor, go to Settings → MCP and add:

{
  "receiptconverter": {
    "command": "npx",
    "args": ["receiptconverter-mcp"],
    "env": { "RECEIPTCONVERTER_API_KEY": "sk_live_your_key" }
  }
}

Build your own MCP wrapper

Need a custom integration? Here's the minimal server — about 40 lines using the MCP SDK:

// receipt-mcp.js  (Node 18+, type: module)
import { Server }               from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";

const server = new Server({ name: "receiptconverter", version: "1.0.0" }, { capabilities: { tools: {} } });

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "convert_receipt",
    description: "Parse a receipt/invoice URL into structured JSON (vendor, total, date, items, taxes).",
    inputSchema: { type: "object", properties: { url: { type: "string" } }, required: ["url"] },
  }],
}));

server.setRequestHandler(CallToolRequestSchema, async ({ params: { name, arguments: args } }) => {
  if (name !== "convert_receipt") throw new Error("Unknown tool");
  const res  = await fetch("https://receiptconverter.com/api/v1/convert", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.RECEIPTCONVERTER_API_KEY}`, "Content-Type": "application/json" },
    body:   JSON.stringify({ url: args.url }),
  });
  const { data } = await res.json();
  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
});

await server.connect(new StdioServerTransport());
npm install @modelcontextprotocol/sdk

AI discovery files

ReceiptConverter publishes several files that AI agents can use for auto-discovery: