MCP Installation

The Ogarni.AI MCP server can be used with any MCP-compatible client. Below are setup instructions for the most common tools.

Remote server (recommended, beta)

The hosted remote server at https://mcp.ogarni.ai/mcp signs you in with OAuth in your browser. You do not create, copy, or store an API token. It is being rolled out in beta and may not be available to your account yet; if the connection fails, use the local server below.

Claude Code

claude mcp add --transport http ogarniai https://mcp.ogarni.ai/mcp

Then run /mcp inside Claude Code, select ogarniai, and sign in with Ogarni in the browser.

Claude, ChatGPT, and other clients with custom connectors

Add https://mcp.ogarni.ai/mcp as a remote MCP server, then complete the Ogarni sign-in and consent page.

Never paste a Firebase token or an Ogarni API token into a remote connector. The remote server currently offers the tools ogarniai_get_financial_overview, ogarniai_get_spending_summary, ogarniai_search_documents, ogarniai_get_document_details, and ogarniai_list_categories. For anything else (receipt images, notifications, groups, mailboxes, loyalty accounts, tags, recurring expenses, weekly summaries), use the local server.

Local server (legacy)

The local server runs on your machine over stdio and authenticates with an API token. It remains supported for the tools the remote server does not offer yet.

Prerequisites

• Node.js 20+ installed on your system.
• An Ogarni.AI API token with read scope. See API tokens for how to create one.

Claude Code

Run a single command to register the MCP server:

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

Claude Code will download and run the server automatically on next startup.

The command serves MCP 2026-07-28 clients and remains compatible with legacy MCP clients. No protocol-version option is required in the server configuration.

Claude Desktop / Cursor / Windsurf

These tools use a JSON configuration file. Add the following entry to your MCP server configuration:

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

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

Cursor — open Settings > MCP Servers and add the same JSON block above.

Windsurf — open Settings > MCP and add the same JSON block above.

Generic JSON config

For any MCP client that accepts a JSON configuration, use this format:

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

Replace oai_your_token with your actual API token.

Local development

If you want to run the server from source (for development or debugging):

# Clone the repository
git clone https://github.com/IsidoreSoftware/ogarniai-mcp.git
cd ogarniai-mcp

# Install dependencies
npm install

# Build the TypeScript source
npm run build

# Run the server (requires the token in your environment)
export OGARNIAI_API_TOKEN="oai_your_token"
npm start

To connect a local build to Claude Code:

claude mcp add ogarniai-mcp \
  -e OGARNIAI_API_TOKEN=oai_your_token \
  -- node /path/to/ogarniai-mcp/dist/index.js

Verifying the connection

Once configured, you can verify the server is working by asking the LLM a question that requires your Ogarni.AI data, such as:

• “What did I spend this week?”
• “Show me my latest receipts.”
• “What are my spending categories?”

The LLM should call the appropriate MCP tool and return results from your account.

Troubleshooting

Problem	Solution
”OGARNIAI_API_TOKEN environment variable is required”	Make sure the token is set in the env config or exported in your shell
Connection timeout	Verify your internet connection and that https://api.ogarni.ai is reachable
401 Unauthorized errors	Your token may be invalid or expired — create a new one in the app
Tools not appearing	Restart your MCP client after changing the configuration
Unsupported Node.js version	Install Node.js 20 or newer and run the server again