Skip to main content
Glama
Sign In
Ogarni.AI MCP Server

Ogarni.AI MCP Server

by IsidoreSoftware
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Ogarni.AI MCP Server

MCP server for read-only access to Ogarni.AI personal finance data.

Supports the MCP 2026-07-28 specification over stdio while remaining compatible with legacy MCP clients (2024-10-07 through 2025-11-25).

Requirements

  • Node.js 20 or newer

  • An Ogarni.AI API token with read access

Related MCP server: ZenMoney MCP

Setup

1. Get an API Token

  1. Download the Ogarni.AI mobile app:

  2. Open the app and go to Settings → API Tokens

  3. Create a new token with read scope

  4. Copy the token (starts with oai_)

2. Install

Claude Code

claude mcp add ogarniai-mcp-server -e OGARNIAI_API_TOKEN=oai_your_token -- npx -y github:IsidoreSoftware/ogarniai-mcp

Claude Desktop / Cursor / Windsurf

Add to your MCP config file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ogarniai": {
      "command": "npx",
      "args": ["-y", "github:IsidoreSoftware/ogarniai-mcp"],
      "env": {
        "OGARNIAI_API_TOKEN": "oai_your_token_here"
      }
    }
  }
}

Important: After adding the config, restart Claude Desktop completely for changes to take effect.

Cursor

Add to .cursorrules or MCP settings:

{
  "mcpServers": {
    "ogarniai": {
      "command": "npx",
      "args": ["-y", "github:IsidoreSoftware/ogarniai-mcp"],
      "env": {
        "OGARNIAI_API_TOKEN": "oai_your_token_here"
      }
    }
  }
}

Windsurf

Add to Windsurf MCP config (Settings → MCP):

{
  "mcpServers": {
    "ogarniai": {
      "command": "npx",
      "args": ["-y", "github:IsidoreSoftware/ogarniai-mcp"],
      "env": {
        "OGARNIAI_API_TOKEN": "oai_your_token_here"
      }
    }
  }
}

Local Development

git clone https://github.com/IsidoreSoftware/ogarniai-mcp.git
cd ogarniai-mcp
npm install
npm run build
OGARNIAI_API_TOKEN=oai_your_token node dist/index.js

Protocol Compatibility

Version 2 uses the official MCP TypeScript SDK v2 and serves the 2026-07-28 protocol through serveStdio. Modern clients use the stateless protocol era with server/discover and per-request metadata. Existing clients can continue using the legacy initialization handshake through the same command.

The server does not keep MCP session state and does not use deprecated roots, sampling, logging, or HTTP+SSE features. See the MCP protocol version guide for the wire-level differences between the modern and legacy eras.

Available Tools

Tool

Description

ogarniai_list_documents

List receipts with date filters and sorting

ogarniai_get_document

Get single receipt details

ogarniai_get_document_image

Get receipt image

ogarniai_get_document_duplicates

Get duplicate suggestions for a document

ogarniai_list_categories

List expense/income categories

ogarniai_list_tags

List user tags

ogarniai_get_weekly_summary

Get latest weekly summary

ogarniai_get_weekly_summary_periods

List available summary periods

ogarniai_get_summary_by_period

Get summary for a custom date range

ogarniai_get_current_period

Get summary for a preset period

ogarniai_list_notifications

List notifications with filters

ogarniai_get_notification

Get notification details

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_dedup_suggestions

List duplicate suggestions

ogarniai_list_loyalty_accounts

List loyalty program accounts

ogarniai_list_supported_banks

List supported banks

ogarniai_get_recurring_expenses

List recurring expenses

Configuration

Environment Variable

Required

Default

Description

OGARNIAI_API_TOKEN

Yes

-

API token (starts with oai_)

OGARNIAI_API_URL

No

https://api.ogarni.ai

API base URL

Security

  • All tools are read-only

  • Token is passed via environment variable, never hardcoded

  • Input validated with Zod schemas

  • Error messages never expose token values

Available Tools

20 tools
ogarniai_get_current_periodGet Current Period SummaryB
Read-onlyIdempotent

Get spending summary for a preset period (current week, current month, etc.).

Args:

  • preset (string): Period preset - "current-week", "current-month", "last-week", or "last-month"

  • granularity (string, optional): Time granularity - "Day" (default), "Week", or "Month"

Returns: JSON with periodStart, periodEnd, totalAmount, dailySummaries[], categoryTotals[]

Inputs: preset (required), granularity.

ogarniai_get_documentGet Purchase DocumentA
Read-onlyIdempotent

Get details of a single purchase document by ID.

Returns full document details including store name, purchase time, total amount, tax, currency, payment method, individual items with categories, tags, and duplicate info.

Args:

  • id (string): Document ID (UUID format)

Returns: JSON object with all document fields including items[] with name, price, quantity, category, subcategory

Inputs: id (required).

ogarniai_get_document_duplicatesGet Document DuplicatesB
Read-onlyIdempotent

Get duplicate suggestions for a specific purchase document.

Args:

  • id (string): Document ID (UUID format)

Returns: JSON with duplicate document suggestions and confidence scores

Inputs: id (required).

ogarniai_get_document_imageGet Document ImageB
Read-onlyIdempotent

Get the scanned image of a purchase document (receipt photo).

Args:

  • id (string): Document ID (UUID format)

Returns: The receipt/document image as base64-encoded data

Inputs: id (required).

ogarniai_get_groupGet Group DetailsA
Read-onlyIdempotent

Get details of a specific finance group.

Args:

  • groupId (string): Group ID (UUID format)

Returns: JSON with group details including id, name, description, owner, isActive, isArchived, memberCount

Inputs: groupId (required).

ogarniai_get_notificationGet Notification DetailsA
Read-onlyIdempotent

Get details of a specific notification.

Args:

  • id (string): Notification ID (UUID format)

Returns: JSON with notification details including id, type, category, title, message, isRead, isUrgent, referenceId, actionUrl

Inputs: id (required).

ogarniai_get_recurring_expensesList Recurring ExpensesA
Read-onlyIdempotent

List recurring expenses (subscriptions, bills, regular payments).

Args:

  • includeInactive (boolean, optional): Include inactive recurring expenses (default: false)

Returns: JSON array of recurring expenses with id, name, description, frequency (Weekly/Monthly/Quarterly/Yearly), category, subcategory, paymentType, nextOccurrenceDate, isActive

Inputs: includeInactive.

ogarniai_get_summary_by_periodGet Summary for Date RangeA
Read-onlyIdempotent

Get a spending summary for a custom date range with configurable granularity.

Args:

  • startDate (string): Start date (ISO 8601, e.g. "2024-01-01")

  • endDate (string): End date (ISO 8601, e.g. "2024-01-31")

  • granularity (string, optional): Time granularity - "Day" (default), "Week", or "Month"

Returns: JSON with periodStart, periodEnd, totalAmount, dailySummaries[], categoryTotals[], detailedCategoryTotals[]

Inputs: endDate (required), startDate (required), granularity.

ogarniai_get_unread_countGet Unread Notification CountA
Read-onlyIdempotent

Get the count of unread notifications.

Returns: JSON with count (number) of unread notifications

Inputs: no named parameters.

ogarniai_get_weekly_summaryGet Latest Weekly SummaryA
Read-onlyIdempotent

Get the most recent weekly spending summary.

Returns a summary with period dates, total amount, daily breakdowns, category totals, and an AI-generated text summary.

Returns: JSON with periodStart, periodEnd, summary (text), dailySummaries[], categoryTotals[], totalAmount

Inputs: no named parameters.

ogarniai_get_weekly_summary_periodsList Weekly Summary PeriodsA
Read-onlyIdempotent

List available weekly summary periods with pagination.

Args:

  • page (number, optional): Page number (default: 1)

  • pageSize (number, optional): Items per page (default: 10)

Returns: JSON array of period summaries with periodStart, periodEnd, totalAmount, summary text

Inputs: page, pageSize.

ogarniai_list_categoriesList CategoriesA
Read-onlyIdempotent

List all available expense/income categories and subcategories.

Returns the full category tree with Polish and English names, emojis, and subcategories with descriptions and examples.

Returns: JSON with categories[], each containing: polishName, englishName, emoji, subCategories[] with polishName, englishName, description, examples, emoji

Inputs: no named parameters.

ogarniai_list_dedup_suggestionsList Deduplication SuggestionsB
Read-onlyIdempotent

List duplicate document suggestions detected by the system.

Returns pairs of documents that may be duplicates, with confidence scores and matching reasons.

Returns: JSON array of suggestions with id, sourceDocumentId, targetDocumentId, confidenceScore (0-1), matchReason, status (Pending/Accepted/Rejected/Dismissed)

Inputs: no named parameters.

ogarniai_list_documentsList Purchase DocumentsA
Read-onlyIdempotent

List receipts and purchase documents with optional date filters and sorting.

Returns a paginated list of purchase documents (receipts, invoices, email purchases) with store name, total amount, items, categories, and tags.

Args:

  • from (string, optional): Start date filter (ISO 8601, e.g. "2024-01-01")

  • to (string, optional): End date filter (ISO 8601, e.g. "2024-12-31")

  • sortBy (string, optional): Sort field - "purchase_time" (default) or "created_at"

  • sortDirection (string, optional): Sort order - "desc" (default) or "asc"

Returns: JSON array of purchase documents with fields: id, storeName, purchaseTime, totalAmount, currency, items[], tags[], groupId, hasDuplicates

Inputs: to, from, sortBy, sortDirection.

ogarniai_list_groupsList GroupsA
Read-onlyIdempotent

List finance groups the user belongs to.

Groups allow sharing expenses with a partner or family members.

Args:

  • showArchived (boolean, optional): Include archived groups (default: false)

Returns: JSON array of groups with id, name, description, ownerId, isActive, isArchived, memberCount, createdAt

Inputs: showArchived.

ogarniai_list_loyalty_accountsList Loyalty AccountsA
Read-onlyIdempotent

List connected external loyalty program accounts (e.g. store loyalty cards).

Returns: JSON array of loyalty connections with id, program, maskedLogin, status, createdAt

Inputs: no named parameters.

ogarniai_list_mailboxesList Inbound MailboxesA
Read-onlyIdempotent

List inbound email addresses for forwarding purchase confirmation emails.

Users can forward emails from stores to these addresses for automatic receipt processing.

Returns: JSON array of mailboxes with id, address, localPart, domain, isPrimary, status, authMode, lastActivityAt

Inputs: no named parameters.

ogarniai_list_notificationsList NotificationsA
Read-onlyIdempotent

List user notifications with optional filters.

Args:

  • isRead (boolean, optional): Filter by read status

  • type (string, optional): Filter by type - "Error", "Warning", "Info", or "Success"

  • category (string, optional): Filter by category - "DocumentProcessing", "WeeklySummary", "System", or "DuplicateDetection"

  • pageSize (number, optional): Items per page (default: 50)

  • pageNumber (number, optional): Page number (default: 1)

Returns: JSON array of notifications with id, type, category, title, message, isRead, isUrgent, actionUrl

Inputs: type, isRead, category, pageSize, +1 more.

ogarniai_list_supported_banksList Supported BanksA
Read-onlyIdempotent

List banks supported for bank statement import.

Returns: JSON array of supported bank names (strings)

Inputs: no named parameters.

ogarniai_list_tagsList TagsA
Read-onlyIdempotent

List all user-defined tags for organizing documents.

Returns: JSON array of tags with id, name, and authorId

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 20 tools

    Disambiguation3/5

    Most tools are clearly distinct collection-vs-single pairs, but there is meaningful overlap among the summary tools (get_weekly_summary, get_current_period, get_summary_by_period) and between get_document_duplicates and list_dedup_suggestions. Descriptions clarify the differences, but an agent could still select the wrong one without close reading.

    Naming Consistency5/5

    All tools follow a consistent ogarniai_<verb>_<noun> pattern, with list_ for collections and get_ for single items or derived values. There is no mixing of naming styles or unpredictable verb choices.

    Tool Count4/5

    20 tools is on the higher side but appropriate for the server's broad scope: documents, summaries, notifications, groups, mailboxes, duplicates, categories, tags, loyalty, and bank support. Each tool addresses a distinct area, though the summary-related tools could be consolidated.

    Completeness3/5

    The server provides strong read-only coverage of the financial document domain, including documents, summaries, duplicates, and notifications. However, there are no mutation tools at all, and obvious workflow steps are missing—such as marking notifications read, resolving duplicate suggestions, or creating/managing groups—which limits completeness for an assistive agent.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Wallet BudgetBakers MCP

      lapin7771n
      A
      license
      A
      quality
      D
      maintenance
      Read-only MCP server for accessing Wallet by BudgetBakers financial data, allowing users to query accounts, transactions, categories, budgets, and more via natural language.
      10
      MIT

    • ZenMoney MCP

      nonnname
      A
      license
      B
      quality
      C
      maintenance
      Read-only MCP server for ZenMoney that syncs financial data into memory and exposes it through tools and resources, enabling agentic analysis of transactions and spending patterns.
      10
      14 npm
      MIT
    • RiseUp MCP Server

      RiseUp MCP Serverofficial

      riseup-oss
      A
      license
      A
      quality
      B
      maintenance
      MCP server for programmatic read-only access to RiseUp cashflow data, allowing AI assistants to retrieve budget information via natural language.
      7
      1,375 npm
      38
      MIT

    • dough-mcp

      rollecode
      A
      license
      B
      quality
      B
      maintenance
      A read-only MCP server for the Dough personal finance app, enabling assistants to query financial data like balances, transactions, and budgets through natural language.
      8
      MIT