MCP Installation

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

Prerequisites

• Node.js 18+ 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.

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