Skip to content

mihirkavi/receiptcal

v0.1.0MIT

Connect ReceiptCal automatic food logging to your AI assistant with confirmed account actions.

GitHubOpen Website

ReceiptCal plugin

Receipts do the logging. Connect your own ReceiptCal account to an AI assistant to inspect food logs, request recipe ideas, and prepare confirmed pantry, planning and support actions.

This is the MIT-licensed developer integration, not the ReceiptCal iOS/Android apps or hosted backend. It is distributed directly on GitHub and is not an approved listing in the OpenAI plugin directory. A GitHub release does not change host eligibility, approval requirements, service terms or account permissions. Hosted use requires a ReceiptCal account and a client that supports OAuth and Streamable HTTP MCP.

Connect to the hosted service

MCP endpoint: https://mcp.receiptcal.com/mcp

Use your client's custom MCP connection flow, then authenticate in ReceiptCal's browser page. Never paste passwords or tokens into chat. Client and workspace policies can restrict custom connections. For ChatGPT, use a custom MCP connection only where your plan/workspace supports it; this repository does not bypass directory review.

Codex

Add this GitHub marketplace using a current Codex client:

codex plugin marketplace add https://github.com/mihirkavi/receiptcal-plugin.git
codex plugin add receiptcal@receiptcal-plugins

Open the client's plugin interface, select receiptcal from receiptcal-plugins, and connect your account. The portable plugin.json/mcp.json are canonical; .codex-plugin/plugin.json supports compatible older clients. Host versions differ; consult OpenAI's installation documentation.

Claude Code

claude plugin marketplace add mihirkavi/receiptcal-plugin
claude plugin install receiptcal@receiptcal-plugins

Authenticate the ReceiptCal server through the host's MCP connection flow. See Claude marketplace documentation.

Develop locally

Node.js 22 or later is required. No backend source checkout is needed.

git clone https://github.com/mihirkavi/receiptcal-plugin.git
cd receiptcal-plugin
npm ci
npm run validate
npm run configure:local

The generated, ignored .mcp.local.json points to the local stdio connector. It is optional; the distributed plugin uses the hosted MCP server. Local account commands include npm run auth -- login and npm run auth -- logout. Enter credentials only in your own terminal. Local auth uses macOS Keychain where available and a permission-restricted local file fallback; environment credentials are supported for controlled development. Do not commit credentials or generated local configuration.

src/capabilities.ts is the typed capability registry; src/server.ts implements MCP tools; src/api-client.ts calls the versioned ReceiptCal APIs; tests use synthetic data and mocked responses. Extend the registry, add schema and behavior tests, run validation, then open a pull request. See CONTRIBUTING.md.

Behavior and limits

  • Account writes are prepared first; show the preview and obtain explicit approval before confirm_action. The account, expiry and single-use checks remain enforced. A few recommendation/quality reads may update derived records.
  • Shopping tools prepare retailer handoffs, never purchases. Nutrition is estimated, with provenance and uncertainty, and is not medical advice.
  • Camera, HealthKit/Health Connect permission flows and live voice capture remain native app features. The optional local connector can upload receipt files from configured allowed roots; default roots are its working directory and Downloads. Restrict RECEIPTCAL_ALLOWED_FILE_ROOTS to a dedicated test directory.
  • API protocol versions are compatibility paths, not app version numbers. Some source capabilities depend on service rollout. V6 community recipes remain gated; a tool existing in source does not prove production availability. Do not retry a disabled capability through older routes.
  • Source tests and protocol checks do not certify a live authenticated journey in every host. See VALIDATION.md.

Privacy, support and licensing

Service privacy · Service terms · Security reporting

File code bugs with synthetic reproduction steps in GitHub issues. Never include receipts, health details, chats, account identifiers, tokens or screenshots containing personal data. Account-specific reports belong in ReceiptCal's private support flow.

The MIT license covers this repository. It does not grant rights to the private app/backend, customer data, third-party content, or ReceiptCal trademarks. The hosted service retains its own terms and availability limits. This release is not published to npm or the MCP Registry.