actual-mcp-server 0.5.4 → 0.5.6

package/README.md

@@ -1,5 +1,7 @@
 # Actual MCP Server
 
+[![npm version](https://img.shields.io/npm/v/actual-mcp-server)](https://www.npmjs.com/package/actual-mcp-server)
+[![npm downloads](https://img.shields.io/npm/dm/actual-mcp-server)](https://www.npmjs.com/package/actual-mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
@@ -17,13 +19,13 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 ┌─────────────┐   MCP/HTTP    ┌──────────────────┐   Actual API   ┌──────────────┐
 │  LibreChat  │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  LobeChat   │               │  Server          │               │   Budget     │
-│  (remote)   │               │  (62 tools)      │               │   Server     │
+│  (remote)   │               │  (63 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 
 ┌─────────────┐   MCP/stdio   ┌──────────────────┐   Actual API   ┌──────────────┐
 │  Claude     │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  Desktop    │               │  Server          │               │   Budget     │
-│  (local)    │               │  (62 tools)      │               │   Server     │
+│  (local)    │               │  (63 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 ```
 
@@ -38,7 +40,7 @@ Most Actual Budget MCP implementations are simple stdio bridges designed for sin
 - **Multi-user ready with OIDC.** Secure every session with JWKS-validated JWTs and per-user budget ACLs — no shared tokens required.
 - **Production-grade reliability.** Connection pooling (up to 15 concurrent sessions), automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).
 
-> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 62 tools tested end-to-end. Any MCP-compatible client should work.
+> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 63 tools tested end-to-end. Any MCP-compatible client should work.
 
 ---
 
@@ -169,7 +171,7 @@ Add to `claude_desktop_config.json` (see [docs/guides/MCP_CLIENTS_SETUP.md](docs
 }
 ```
 
-> **No token needed.** stdio runs as a local process owned by your user — the transport itself is the security boundary. All 62 tools are available.
+> **No token needed.** stdio runs as a local process owned by your user — the transport itself is the security boundary. All 63 tools are available.
 >
 > **`MCP_BRIDGE_DATA_DIR` should be an absolute path** — without it, the data directory resolves relative to wherever the client spawns the process, which can be unpredictable. The directory is created automatically on first run.
 
@@ -234,7 +236,7 @@ See [docs/guides/MCP_CLIENTS_SETUP.md](docs/guides/MCP_CLIENTS_SETUP.md) for all
 
 ## Available Tools
 
-**62 tools** across 12 categories. All tools use the `actual_<category>_<action>` naming convention.
+**63 tools** across 12 categories. All tools use the `actual_<category>_<action>` naming convention.
 
 ### Accounts (7)
 
@@ -272,6 +274,14 @@ See [docs/guides/MCP_CLIENTS_SETUP.md](docs/guides/MCP_CLIENTS_SETUP.md) for all
 | `actual_transactions_summary_by_category` | Spending summary grouped by category |
 | `actual_transactions_summary_by_payee` | Top vendors with totals and counts |
 
+### Transfers (1)
+
+| Tool | Description |
+|------|-------------|
+| `actual_transfers_create` | Create a paired transfer between two accounts (debit + credit linked by `transfer_id`, identical to UI "Make Transfer") |
+
+> **How transfers work under the hood** — Actual Budget requires the `runTransfers: true` option when adding transactions so that both sides (the debit on the source account and the credit on the destination account) are created and linked via a shared `transfer_id`. Prior to v0.5.6, the adapter forwarded a hardcoded empty options object `{}` to `rawAddTransactions`, silently dropping any options including this flag. This meant that calling `actual_transfers_create` would appear to succeed but only one side of the transfer would be recorded. The fix ensures options are forwarded correctly; use `actual_transfers_create` (not `actual_transactions_create`) for all account-to-account moves.
+
 ### Categories (4)
 
 `actual_categories_get` · `actual_categories_create` · `actual_categories_update` · `actual_categories_delete`
@@ -446,7 +456,7 @@ stdio is the simplest way to connect Claude Desktop directly to Actual Budget. T
 - No auth token — process ownership is the security boundary
 - All logs go to stderr so they never corrupt the JSON-RPC framing on stdout
 - The process exits when stdin closes (Claude Desktop shutting down)
-- All 62 tools are available, identical to HTTP mode
+- All 63 tools are available, identical to HTTP mode
 
 **Start manually to verify:**
 
@@ -523,7 +533,7 @@ See [AI Client Setup — OIDC](docs/guides/AI_CLIENT_SETUP.md#oidc-authenticatio
 | Command | What It Tests | Requires Live Server |
 |---------|---------------|---------------------|
 | `npm run build` | TypeScript compilation | No |
-| `npm run test:unit-js` | 62-tool smoke, schema validation, auth ACL | No |
+| `npm run test:unit-js` | 63-tool smoke, schema validation, auth ACL | No |
 | `npm run test:adapter` | Adapter, retry logic, concurrency | No |
 | `npm run test:e2e` | MCP protocol compliance (Playwright) | No |
 | `npm run test:e2e:docker:full` | Full stack integration | Yes (Docker) |
@@ -565,7 +575,7 @@ Several MCP servers exist for personal finance management. Here's how this proje
 | **Version** | v0.4.26 | v1.11.1 | v0.2.0 | v0.1.0 |
 | **Budget App** | Actual Budget (self-hosted) | Actual Budget (self-hosted) | Actual Budget (self-hosted) | YNAB (cloud, subscription) |
 | **Language** | TypeScript / Node.js | TypeScript / Node.js | TypeScript / Node.js | Python |
-| **Tool Count** | **62** | ~22 | 18 | 9 |
+| **Tool Count** | **63** | ~22 | 18 | 9 |
 | **— Setup & Distribution —** |||||
 | **Transport** | HTTP + stdio | STDIO + SSE option | STDIO | STDIO |
 | **Docker support** | ✅ Full (image + Compose) | ✅ Image only | ❌ | ❌ |
@@ -668,4 +678,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.5.4 | **Tool Count:** 62 (verified LibreChat-compatible)
+**Version:** 0.5.6 | **Tool Count:** 63 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.5.4",
+    "version": "0.5.6",
     "engines": {
         "node": ">=20.0.0",
         "npm": ">=10.0.0"
@@ -58,13 +58,18 @@
     "dependencies": {
         "@actual-app/api": "^26.4.0",
         "@modelcontextprotocol/sdk": "^1.29.0",
+        "debug": "^4.4.3",
         "dotenv": "^17.4.1",
         "express": "^5.2.1",
+        "jose": "^6.1.3",
         "mcp-auth": "^0.2.0",
         "winston": "^3.18.3",
         "winston-daily-rotate-file": "^5.0.0",
         "zod": "^4.0.0"
     },
+    "optionalDependencies": {
+        "prom-client": "*"
+    },
     "overrides": {
         "ajv": "8.18.0",
         "qs": "6.14.2"
@@ -76,6 +81,7 @@
         "@playwright/test": "^1.59.1",
         "@types/express": "^5.0.3",
         "@types/node": "^25.6.0",
+        "node-fetch": "^3.3.2",
         "tsconfig-paths": "^4.2.0",
         "typescript": "^6.0.2"
     },

package/dist/src/actualToolsManager.js

@@ -60,6 +60,7 @@ const IMPLEMENTED_TOOLS = [
     'actual_transactions_uncategorized',
     'actual_transactions_update',
     'actual_transactions_update_batch',
+    'actual_transfers_create',
     'actual_server_info',
     'actual_session_close',
     'actual_session_list',

package/dist/src/config.js

@@ -32,7 +32,11 @@ export const configSchema = z.object({
 function getConfig() {
     const result = configSchema.safeParse(process.env);
     if (!result.success) {
-        console.error('Invalid or missing environment variables:', result.error.issues);
+        const missing = result.error.issues.map(i => `  • ${i.path.join('.')}`).join('\n');
+        console.error(`\n❌ Missing or invalid environment variables:\n${missing}\n\n` +
+            `Set them in a .env file in the current directory, or export them before running.\n` +
+            `Required: ACTUAL_SERVER_URL, ACTUAL_PASSWORD, ACTUAL_BUDGET_SYNC_ID\n` +
+            `See: https://github.com/agigante80/actual-mcp-server\n`);
         process.exit(1);
     }
     return result.data;

package/dist/src/index.js

@@ -80,6 +80,15 @@ if (argsEarly.includes('--stdio')) {
 // Only load dotenv if we're not just showing help
 // dotenv will be loaded inside the async IIFE below via dynamic import
 // to avoid using require() in ESM and to keep the early --help fast exit.
+const KNOWN_FLAGS = new Set([
+    '--http', '--stdio', '--test-actual-connection', '--test-mcp-client',
+    '--debug', '--help', '-h', '--version', '-v',
+]);
+const unknownFlags = argsEarly.filter(a => a.startsWith('-') && !KNOWN_FLAGS.has(a));
+if (unknownFlags.length > 0) {
+    console.error(`Unknown option: ${unknownFlags.join(', ')}\nRun \`actual-mcp-server --help\` for usage.`);
+    process.exit(1);
+}
 if (argsEarly.includes('--help') || argsEarly.includes('-h') ||
     argsEarly.includes('--version') || argsEarly.includes('-v')) {
     const pkg = await import('../package.json', { with: { type: 'json' } });

package/dist/src/lib/actual-adapter.js

@@ -333,7 +333,7 @@ export async function getAccounts() {
     });
 }
 // addTransactions returns various formats: "ok", array of IDs, or Transaction objects
-export async function addTransactions(txs) {
+export async function addTransactions(txs, options = {}) {
     observability.incrementToolCall('actual.transactions.create').catch(() => { });
     return queueWriteOperation(async () => {
         // The Actual API expects addTransactions(accountId, transactions, options)
@@ -352,7 +352,7 @@ export async function addTransactions(txs) {
             return rest;
         });
         // API docs say it returns id[], but reality is it can return "ok", array of IDs, or Transaction objects
-        const result = await withConcurrency(() => retry(() => rawAddTransactions(accountId, cleanedTxs, {}), { retries: 2, backoffMs: 200 }));
+        const result = await withConcurrency(() => retry(() => rawAddTransactions(accountId, cleanedTxs, options), { retries: 2, backoffMs: 200 }));
         // Handle various return formats
         if (result === 'ok') {
             // Transaction created successfully but no IDs returned
@@ -383,6 +383,45 @@ export async function importTransactions(accountId, txs) {
         return raw || { added: [], updated: [], errors: [] };
     });
 }
+export async function createTransfer(params) {
+    observability.incrementToolCall('actual.transfers.create').catch(() => { });
+    return queueWriteOperation(async () => {
+        if (params.from_account === params.to_account) {
+            return { success: false, error: 'from_account and to_account must be different accounts.' };
+        }
+        const accounts = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const fromAcc = accounts.find((a) => a.id === params.from_account);
+        const toAcc = accounts.find((a) => a.id === params.to_account);
+        if (!fromAcc)
+            return { success: false, error: `Account '${params.from_account}' not found. Use actual_accounts_list to find valid accounts.` };
+        if (fromAcc.closed)
+            return { success: false, error: `Source account '${fromAcc.name}' is closed.` };
+        if (!toAcc)
+            return { success: false, error: `Account '${params.to_account}' not found. Use actual_accounts_list to find valid accounts.` };
+        if (toAcc.closed)
+            return { success: false, error: `Destination account '${toAcc.name}' is closed.` };
+        const payees = await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
+        const transferPayee = payees.find((p) => p.transfer_acct === params.to_account && !p.tombstone);
+        if (!transferPayee) {
+            return { success: false, error: `No transfer payee found for destination account '${toAcc.name}'. The account may not support transfers.` };
+        }
+        const sourceTx = {
+            date: params.date,
+            amount: -Math.abs(params.amount),
+            payee: transferPayee.id,
+            ...(params.notes !== undefined && { notes: params.notes }),
+        };
+        const result = await withConcurrency(() => retry(() => rawAddTransactions(params.from_account, [sourceTx], { runTransfers: true }), { retries: 2, backoffMs: 200 }));
+        let from_id = null;
+        if (Array.isArray(result) && result.length > 0 && typeof result[0] === 'string' && result[0] !== 'ok') {
+            from_id = result[0];
+        }
+        else if (result && typeof result === 'object' && 'id' in result) {
+            from_id = result.id;
+        }
+        return { success: true, from_id, to_id: null };
+    });
+}
 export async function getTransactions(accountId, startDate, endDate) {
     return withActualApi(async () => {
         observability.incrementToolCall('actual.transactions.get').catch(() => { });
@@ -1178,6 +1217,7 @@ export default {
     getAccountsWithBalances,
     addTransactions,
     importTransactions,
+    createTransfer,
     getTransactions,
     getCategories,
     createCategory,

package/dist/src/tools/index.js

@@ -59,5 +59,6 @@ export { default as transactions_summary_by_payee } from './transactions_summary
 export { default as transactions_uncategorized } from './transactions_uncategorized.js';
 export { default as transactions_update } from './transactions_update.js';
 export { default as transactions_update_batch } from './transactions_update_batch.js';
+export { default as transfers_create } from './transfers_create.js';
 export { default as session_close } from './session_close.js';
 export { default as session_list } from './session_list.js';

package/dist/src/tools/transfers_create.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
+import adapter from '../lib/actual-adapter.js';
+const positiveAmountCents = z
+    .number()
+    .int('Amount must be an integer (cents)')
+    .positive('Amount must be a positive integer in cents (e.g. 5000 = $50.00)');
+export default createTool({
+    name: 'actual_transfers_create',
+    description: 'Create a paired transfer between two accounts — a debit on the source account and a credit ' +
+        'on the destination account, linked by a shared transfer_id. Identical to the Actual Budget UI ' +
+        '"Make Transfer" result. Amount must be a positive integer in cents (e.g. 5000 = $50.00). ' +
+        'Both accounts must be open. Use actual_accounts_list to look up account UUIDs. ' +
+        'Note: if both accounts are bank-synced via GoCardless, a duplicate may appear after the next ' +
+        'sync if the bank settles the two sides on different dates.',
+    schema: z.object({
+        from_account: CommonSchemas.accountId.describe('UUID of the source account (money leaves this account)'),
+        to_account: CommonSchemas.accountId.describe('UUID of the destination account (money enters this account)'),
+        amount: positiveAmountCents,
+        date: CommonSchemas.date,
+        notes: z.string().max(1000).optional().describe('Optional memo visible on both sides of the transfer'),
+    }),
+    handler: async (input) => adapter.createTransfer(input),
+    examples: [
+        {
+            description: 'Transfer $50.00 from Checking to Credit Card',
+            input: { from_account: 'uuid-checking', to_account: 'uuid-cc', amount: 5000, date: '2024-01-15' },
+        },
+    ],
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"
@@ -58,13 +58,18 @@
   "dependencies": {
     "@actual-app/api": "^26.4.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "debug": "^4.4.3",
     "dotenv": "^17.4.1",
     "express": "^5.2.1",
+    "jose": "^6.1.3",
     "mcp-auth": "^0.2.0",
     "winston": "^3.18.3",
     "winston-daily-rotate-file": "^5.0.0",
     "zod": "^4.0.0"
   },
+  "optionalDependencies": {
+    "prom-client": "*"
+  },
   "overrides": {
     "ajv": "8.18.0",
     "qs": "6.14.2"
@@ -76,6 +81,7 @@
     "@playwright/test": "^1.59.1",
     "@types/express": "^5.0.3",
     "@types/node": "^25.6.0",
+    "node-fetch": "^3.3.2",
     "tsconfig-paths": "^4.2.0",
     "typescript": "^6.0.2"
   },