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)
Section titled “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
Section titled “Claude Code”claude mcp add --transport http ogarniai https://mcp.ogarni.ai/mcpThen run /mcp inside Claude Code, select ogarniai, and sign in with Ogarni in the browser.
Claude (claude.ai, Desktop, mobile)
Section titled “Claude (claude.ai, Desktop, mobile)”In settings, open Connectors and add a custom connector with the URL https://mcp.ogarni.ai/mcp. Leave the OAuth Client ID and Client Secret fields empty: Claude registers itself. After saving, click Connect and sign in with Ogarni.
ChatGPT
Section titled “ChatGPT”Add a new app (connector) with the URL https://mcp.ogarni.ai/mcp and OAuth authentication. Do not enter a client ID; ChatGPT registers itself.
VS Code (GitHub Copilot)
Section titled “VS Code (GitHub Copilot)”Add to .vscode/mcp.json:
{ "servers": { "ogarniai": { "type": "http", "url": "https://mcp.ogarni.ai/mcp" } }}Cursor
Section titled “Cursor”Add to ~/.cursor/mcp.json:
{ "mcpServers": { "ogarniai": { "url": "https://mcp.ogarni.ai/mcp" } }}Codex CLI
Section titled “Codex CLI”codex mcp add ogarniai --url https://mcp.ogarni.ai/mcpcodex mcp login ogarniaiGemini CLI and other clients
Section titled “Gemini CLI and other clients”In Gemini CLI, add a server with "httpUrl": "https://mcp.ogarni.ai/mcp" to settings.json. In any other client, add https://mcp.ogarni.ai/mcp as a remote MCP server (Streamable HTTP), then complete the Ogarni sign-in and consent page.
The server supports both standard ways to register an OAuth client: Client ID Metadata Documents (Claude, ChatGPT, VS Code) and Dynamic Client Registration (Cursor, Codex, Gemini CLI, MCP Inspector). You don’t need to register anything by hand.
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)
Section titled “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
Section titled “Prerequisites”- Node.js 20+ installed on your system.
- An Ogarni.AI API token with
readscope. See API tokens for how to create one.
Claude Code
Section titled “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-mcpClaude 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
Section titled “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
Section titled “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
Section titled “Local development”If you want to run the server from source (for development or debugging):
# Clone the repositorygit clone https://github.com/IsidoreSoftware/ogarniai-mcp.gitcd ogarniai-mcp
# Install dependenciesnpm install
# Build the TypeScript sourcenpm run build
# Run the server (requires the token in your environment)export OGARNIAI_API_TOKEN="oai_your_token"npm startTo 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.jsVerifying the connection
Section titled “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
Section titled “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 |