actual-mcp-server 0.5.5 → 0.5.7

package/README.md

@@ -19,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     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 ```
 
@@ -40,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.
 
 ---
 
@@ -171,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.
 
@@ -236,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)
 
@@ -274,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`
@@ -448,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:**
 
@@ -525,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) |
@@ -567,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 | ❌ | ❌ |
@@ -670,4 +678,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.5.5 | **Tool Count:** 62 (verified LibreChat-compatible)
+**Version:** 0.5.7 | **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.5",
+    "version": "0.5.7",
     "engines": {
         "node": ">=20.0.0",
         "npm": ">=10.0.0"

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/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/transactions_uncategorized.js

@@ -22,7 +22,7 @@ const InputSchema = z.object({
 });
 const tool = {
     name: 'actual_transactions_uncategorized',
-    description: 'List uncategorized transactions (category is null/unset). Useful for cleanup workflows and rule-suggestion prompts. Defaults to the current month unless a date range is provided. Returns { transactions, count, summary: { totalAmount }, dateRange }.',
+    description: 'List uncategorized transactions (category is null/unset). Excludes transfers, split-transaction parents, opening balance entries, off-budget accounts, and closed accounts — matching Actual Budget\'s own Uncategorized view. Defaults to the current month unless a date range is provided. Returns { transactions, count, summary: { totalAmount }, dateRange }.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
@@ -38,17 +38,21 @@ const tool = {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const txnRaw = await adapter.getTransactions(accountId, startDate, endDate);
         const txns = Array.isArray(txnRaw) ? txnRaw : [];
-        // Fetch accounts to build off-budget exclusion set.
+        // Fetch accounts to build exclusion set: off-budget + closed accounts.
         const accounts = await adapter.getAccounts();
-        const offBudgetIds = new Set(
+        const excludedAccountIds = new Set(
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         (Array.isArray(accounts) ? accounts : [])
-            .filter((acc) => acc?.offbudget === true)
+            .filter((acc) => acc?.offbudget === true || acc?.closed === true)
             .map((acc) => acc.id));
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const uncategorized = txns.filter(
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (txn) => txn?.category == null && !offBudgetIds.has(txn?.account));
+        (txn) => txn?.category == null &&
+            txn?.transfer_id == null &&
+            txn?.is_parent !== true &&
+            txn?.starting_balance_flag !== true &&
+            !excludedAccountIds.has(txn?.account));
         const limited = uncategorized.slice(0, input.limit ?? 500);
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const totalAmount = limited.reduce((sum, txn) => {

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.5",
+  "version": "0.5.7",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"