Money Lover MCP Server

Node.js implementation of a Model Context Protocol (MCP) server that wraps the unofficial Money Lover REST API. The server exposes 27 MCP tools covering authentication, wallets, categories, transactions, events, debts, and static configuration — enabling AI assistants or MCP-compatible clients to query and manage personal finance data.

Features

• Auto-authentication via EMAIL/PASSWORD environment variables — no token passing required for most tools.

• 23 read tools covering user info, wallets, categories, transactions, events, debts, icons, providers, and static config.

• 4 write tools: create, update, and delete transactions, wallets, and categories.

• Large responses truncated automatically to keep LLM context manageable (configurable via limit parameter).

• Stdio-based server compatible with Claude Code, Claude Desktop, Cursor, and any MCP host.

• Token caching per email under ~/.moneylover-mcp/ with automatic refresh on auth errors.

Prerequisites

• Node.js 22 or newer.

• Money Lover account credentials.

Installation

npm install

Usage

Launch the MCP server over stdio:

npm start

Project-scoped Configuration (Claude Code)

Add .mcp.json at the project root:

{
  "mcpServers": {
    "mcp-moneylover": {
      "command": "node",
      "args": ["/absolute/path/to/moneylover-mcp/src/server.js"],
      "env": {
        "EMAIL": "your@email.com",
        "PASSWORD": "your-password"
      }
    }
  }
}

And enable it in .claude/settings.json:

{ "enabledMcpjsonServers": ["mcp-moneylover"] }

Global Configuration (Claude Desktop / Cursor)

{
  "mcpServers": {
    "mcp-moneylover": {
      "command": "npx",
      "args": ["@ferdhika31/moneylover-mcp@latest"],
      "env": {
        "EMAIL": "your@email.com",
        "PASSWORD": "your-password"
      }
    }
  }
}

Available Tools

Auth

User

Wallets

Categories

Transactions

Static & Config

Tool Usage Examples

Prompt examples, required vs optional fields, gotchas, and common multi-step patterns for every tool: docs/examples.md.

Library Usage

import { MoneyloverClient } from './src/moneyloverClient.js';

const token = await MoneyloverClient.getToken(email, password);
const client = new MoneyloverClient(token);

const wallets = await client.getWallets();
const txns = await client.getTransactions(walletId, '2026-01-01', '2026-04-30');
await client.addTransaction({ walletId, categoryId, amount: '50000', date: '2026-04-18' });
await client.editTransaction('txn-id', { amount: '60000', note: 'updated' });
await client.deleteTransaction('txn-id');

Testing

Unit Tests

Mocked unit tests — no live API calls required:

npm test

Integration Tests (mcp-tester)

mcp-tester is a ReAct-agent-based MCP testing framework. It starts the server, drives an LLM to call tools in response to natural-language prompts, and asserts the correct tools were called with correct arguments.

Install

pipx install --index-url https://pypi.artifacts.furycloud.io/simple/ mcp-tester

Configure

tests/mcp-tester/mcps.json — point at the local server with your credentials:

{
  "mcp-moneylover": {
    "command": "node",
    "args": ["/absolute/path/to/src/server.js"],
    "transport": "stdio",
    "env": {
      "EMAIL": "your@email.com",
      "PASSWORD": "your-password"
    }
  }
}

Run

mcp-tester run-tests \
  --mcps tests/mcp-tester/mcps.json \
  --model gpt-4o-mini \
  --concurrent-runs 3 \
  tests/mcp-tester/read-tools.yaml

Results

tests/mcp-tester/read-tools.yaml contains 25 integration tests covering every read tool:

total 25, success 25, failures 0

Key decisions that make the tests stable:

• No token parameter on read tools — exposing an optional token field caused LLMs to inject wallet IDs into it. The server authenticates automatically via env vars.

• Response truncation — several endpoints return hundreds of thousands of records from the shared MoneyLover database. Tools accept a limit parameter (default: 20–100) to keep LLM context under control.

• Dict wrapping — all tool responses return a JSON object (never a bare array) so MCP framework validation passes.

Write-Tool Tests (mcp-tester)

Three additional YAML files test the full CRUD lifecycle for wallets, categories, and transactions across three sequential phases. Each phase runs all three resource types concurrently.

Run phases in order — each depends on the previous:

# Phase 1: Create
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-create.yaml

# Phase 2: Edit (after Phase 1 passes)
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-edit.yaml

# Phase 3: Delete (after Phase 2 passes)
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-delete.yaml

Results across all three phases:

Phase 1 (Create): total 3, success 3, failures 0
Phase 2 (Edit):   total 3, success 3, failures 0
Phase 3 (Delete): total 3, success 3, failures 0

Key design decisions for write-tool tests:

• Discovery before mutation — Edit and delete tests instruct the agent to first call a read tool (get_wallets, get_categories, get_transactions) to locate the target by name, then call the mutation tool. This mirrors real-world agent behaviour where IDs are not known in advance.

• args: !any for write tool assertions — The framework requires exact arg matching. Write tools accept optional fields (icon, with, etc.) that the agent may include at its discretion; !any verifies the tool was called and succeeded without failing on harmless extras. Read-tool assertions can use exact arg matching because their schemas have no optional fields the LLM would add spontaneously.

• Predictable identifiers — Test resources use fixed names (MCP-Test-Wallet, MCP-Test-Category) and a fixed note (MCP test transaction) so the agent can locate them by name during the edit and delete phases without needing to share state between test runs.

• Full-payload edit assertions — edit_transaction is a full-replace operation; the test prompt instructs the agent to fetch the existing transaction first (get_transactions) and carry forward all current field values, only changing the note. This validates the multi-step reasoning the tool description requires.

Security Notes

• Never commit real credentials or tokens.

• Cached tokens live in ~/.moneylover-mcp/ restricted to the current user.

• Delete that directory to revoke all cached sessions.