# Agni Folio MCP Server

[![CI](https://github.com/nivela-tech/agnifolio-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/nivela-tech/agnifolio-mcp/actions/workflows/ci.yml)
[![agnifolio-mcp MCP server](https://glama.ai/mcp/servers/nivela-tech/agnifolio-mcp/badges/score.svg)](https://glama.ai/mcp/servers/nivela-tech/agnifolio-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Official [Model Context Protocol](https://modelcontextprotocol.io) server for [Agni Folio](https://agnifolio.com) — a free, multi-currency wealth & portfolio tracker (stocks, crypto, real estate, fixed deposits, mutual funds, insurance, and loans across 20+ markets).

This is a **hosted remote server**. There is nothing to install or run — you connect your MCP client to the production endpoint and authenticate with your own Agni Folio account.

- **Endpoint:** `https://agnifolio.com/mcp` (streamable HTTP)
- **Auth:** OAuth 2.1 with Dynamic Client Registration + PKCE — any MCP client can onboard without pre-registration
- **Scopes:** `agnifolio:read`, `agnifolio:write` (per-user, revocable from *Settings → Connected AI*)
- **Server card:** [`/.well-known/mcp/server-card.json`](https://agnifolio.com/.well-known/mcp/server-card.json)
- **Agent skills:** [`/.well-known/agent-skills/index.json`](https://agnifolio.com/.well-known/agent-skills/index.json)
- **Docs:** [Connect Your AI](https://agnifolio.com/docs/features/connect-your-ai) · [auth.md](https://agnifolio.com/auth.md) · [llms.txt](https://agnifolio.com/llms.txt)

## Quick connect

**Claude (web/desktop):** Settings → Connectors → *Add custom connector* → `https://agnifolio.com/mcp` → complete the OAuth sign-in.

**Cursor / Cline / Continue / other stdio-first clients** — bridge via [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json
{
  "mcpServers": {
    "agnifolio": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://agnifolio.com/mcp"]
    }
  }
}
```

The first call opens a browser window for the OAuth consent flow; tokens are cached locally by `mcp-remote`.

## Public-tools server (open source, in this repo)

This repo also contains a small **runnable MCP server** for Agni Folio's public tools — no account needed:

| Tool | What it does |
|---|---|
| `calculate_fire_number` | FIRE number, progress %, years-to-FIRE, Coast FIRE — pure local math |
| `get_high_interest_products` | Current savings/FD/treasury rates across SG, IN, US (public API) |
| `find_networth_percentile` | Net-worth percentile by country/age/gender (anonymized public dataset) |
| `get_agnifolio_info` | About Agni Folio + how to connect to the personal-data server |

```bash
npm install && npm run build
node dist/index.js          # stdio MCP server

# or via Docker
docker build -t agnifolio-public-mcp .
docker run -i --rm agnifolio-public-mcp
```

Claude Desktop / Cursor config:

```json
{
  "mcpServers": {
    "agnifolio-public": {
      "command": "node",
      "args": ["/path/to/agnifolio-mcp/dist/index.js"]
    }
  }
}
```

The public-tools server never sees credentials; personal portfolio data is only available through the hosted OAuth server above.

## Tools (23)

**Read — portfolio:** `query_holdings`, `query_holding_by_symbol`, `query_account_summary`, `query_performance_summary`, `query_classification_warnings`

**Read — FIRE planning:** `query_user_fire_status`, `query_user_coast_fire`, `query_fire_what_if`

**Read — crypto & trading:** `query_crypto_pnl`, `query_exchange_spot_balances`, `query_open_positions`, `query_margin_detail`, `query_recent_trades`

**Read — protection & legacy:** `query_insurance_summary`, `query_nominees`

**Write (confirm-gated):** `add_portfolio_entry`, `add_transaction`, `add_insurance_policy`, `delete_portfolio_entry`, `parse_text_into_entries`, `set_crypto_cost_basis`, `recover_crypto_cost_basis`, `update_user_fire_goals`

Every mutating tool is **confirm-before-execute**: the change is staged and must be approved inside the Agni Folio app before it takes effect. Every external call — read or write — is recorded in a per-user audit log.

## Security model

- Per-user OAuth tokens; the server never sees your client's credentials
- Scoped access (`read` vs `write`) chosen at consent time
- Revocation: one click in *Settings → Connected AI* kills the grant
- Confirm-gated writes + full audit trail
- Agni Folio is not a brokerage and executes no trades; it is a tracking/analytics tool

## About this repository

The server implementation is part of the Agni Folio production backend and is not open source; this repository is the canonical public home for connection docs and issue reports for the MCP surface. Found a problem with a tool? [Open an issue](../../issues) or use [contact](https://agnifolio.com/contact-us).