MCP Server
The Ogarni.AI MCP server is a Model Context Protocol server that lets LLMs like Claude interact with your personal finance data directly. Instead of manually copying data between the app and your AI assistant, the MCP server gives the model structured access to all read-only API endpoints as tools.
What it does
Section titled “What it does”The server exposes 20 read-only tools that map to the Ogarni.AI API endpoints. When connected to an MCP-compatible client (Claude Code, Claude Desktop, Cursor, Windsurf, etc.), the LLM can call these tools to:
- List and search your purchase documents (receipts, invoices)
- Retrieve spending summaries by week, month, or custom date range
- Browse categories, tags, and recurring expenses
- Check notifications and group details
- View inbound mailboxes, loyalty accounts, and bank statement support
- Detect duplicate documents
Available tools
Section titled “Available tools”| Tool | Description |
|---|---|
ogarniai_list_documents | List purchase documents with date and sort filters |
ogarniai_get_document | Get full details of a single document |
ogarniai_get_document_image | Get the scanned receipt image |
ogarniai_get_document_duplicates | Get duplicate suggestions for a document |
ogarniai_list_categories | List expense/income categories |
ogarniai_list_tags | List user-defined tags |
ogarniai_get_latest_weekly_summary | Get the most recent weekly summary |
ogarniai_list_weekly_summaries | List weekly summaries with pagination |
ogarniai_get_period_summary | Get summary for a custom date range |
ogarniai_get_preset_summary | Get summary for a preset period |
ogarniai_list_notifications | List notifications with filters |
ogarniai_get_notification | Get a single notification |
ogarniai_get_unread_count | Get unread notification count |
ogarniai_list_groups | List finance groups |
ogarniai_get_group | Get group details |
ogarniai_list_mailboxes | List inbound email addresses |
ogarniai_list_deduplication_suggestions | List duplicate document suggestions |
ogarniai_list_loyalty_accounts | List loyalty program connections |
ogarniai_list_supported_banks | List supported banks for statement import |
ogarniai_get_profile | Get user profile information |
Configuration
Section titled “Configuration”The server requires one environment variable and accepts an optional second:
| Variable | Required | Default | Description |
|---|---|---|---|
OGARNIAI_API_TOKEN | Yes | — | Your API token (with oai_ prefix) |
OGARNIAI_API_URL | No | https://api.ogarni.ai | API base URL |
Security
Section titled “Security”The MCP server is designed with security in mind:
- Read-only. All 20 tools are strictly read-only. The server cannot modify, create, or delete any data.
- Input validation. Every tool validates its inputs using Zod schemas before making API calls.
- No token exposure. The API token is used only in outgoing HTTP headers and is never returned in tool responses.
- Scoped access. The server only needs a
readscope token — no write or admin permissions required.
Next steps
Section titled “Next steps”- Installation — Set up the MCP server with your preferred client.
- API endpoints — See what data each tool provides.