actual-mcp-server 0.20.0 → 0.21.0

package/README.md

@@ -24,13 +24,13 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 ┌─────────────┐   MCP/HTTP    ┌──────────────────┐   Actual API   ┌──────────────┐
 │  LibreChat  │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  LobeChat   │               │  Server          │               │   Budget     │
-│  (remote)   │               │  (77 tools)      │               │   Server     │
+│  (remote)   │               │  (81 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 
 ┌─────────────┐   MCP/stdio   ┌──────────────────┐   Actual API   ┌──────────────┐
 │  Claude     │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  Desktop    │               │  Server          │               │   Budget     │
-│  (local)    │               │  (77 tools)      │               │   Server     │
+│  (local)    │               │  (81 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 ```
 
@@ -38,14 +38,14 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 
 Most Actual Budget MCP implementations are simple stdio bridges designed for single-user, local use with Claude Desktop. This project goes further:
 
-- **77 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers the reachable Actual Budget API with no genuine gaps.
+- **81 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers the reachable Actual Budget API with no genuine gaps.
 - **HTTP and stdio transport.** Runs as a real remote server for LibreChat/LobeChat (`--http`), or as a direct local process for Claude Desktop (`--stdio`). No Docker or HTTP server is needed for local use.
 - **6 exclusive ActualQL-powered tools.** Search and summarise transactions by month, amount, category, or payee using Actual Budget's native query engine. Aggregated results, no raw data dumped into the AI context window.
 - **Multi-budget switching at runtime.** Configure multiple budget files and let the AI switch between them mid-conversation with `actual_budgets_switch`. Works on both transports: HTTP keys the active budget to the MCP session, and stdio (Claude Desktop, Claude Code, Cursor) gets a synthetic per-process session so a switch is scoped to that process rather than shared globally (#348).
 - **Multi-user ready with OIDC.** Secure every session with JWKS-validated JWTs and per-user budget ACLs. No shared tokens required.
 - **Production-grade reliability on both transports.** HTTP connection pooling (up to 15 concurrent sessions), and a long-lived stdio process that logs in ONCE and reuses that connection for every tool call instead of re-authenticating per call, so Claude Desktop and Claude Code stay fast and a burst of calls no longer risks a per-call login storm against the upstream limiter. 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 77 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 81 tools tested end-to-end. Any MCP-compatible client should work.
 
 ---
 
@@ -182,7 +182,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 77 tools are available.
+> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 81 tools are available.
 >
 > **`MCP_BRIDGE_DATA_DIR` should be an absolute path.** Without one, the data directory resolves relative to wherever the client spawns the process, which can be unpredictable. The directory is created automatically on first run.
 
@@ -308,9 +308,9 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 ## Available Tools
 
-**77 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
+**81 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
 
-### Accounts (8)
+### Accounts (12)
 
 | Tool | Description |
 |------|-------------|
@@ -322,6 +322,10 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_accounts_reopen` | Reopen closed account. An id that is not an account is refused rather than creating one |
 | `actual_accounts_get_balance` | Get account balance at a date |
 | `actual_account_flow_summary` | Explain the exact balance change across a set of accounts over a date range: external income, expense outflow, credits, uncategorized inflows, and transfers into, out of, or within the selection, with an exact reconciliation |
+| `actual_account_groups_list` | List the custom account groups used to organise accounts in the sidebar (Actual 26.9.0+) |
+| `actual_account_groups_create` | Create an account group. Assigning accounts to it is a separate `actual_accounts_update` call |
+| `actual_account_groups_update` | Rename an account group or change its sidebar position. A group that does not exist is refused, writing nothing |
+| `actual_account_groups_delete` | Delete an account group. Its accounts are NOT deleted, they become ungrouped |
 
 ### Transactions (16)
 
@@ -594,7 +598,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 77 tools are available, identical to HTTP mode
+- All 81 tools are available, identical to HTTP mode
 
 **Start manually to verify:**
 
@@ -693,7 +697,7 @@ See [AI Client Setup, OIDC](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-m
 | Command | What It Tests | Requires Live Server |
 |---------|---------------|---------------------|
 | `npm run build` | TypeScript compilation | No |
-| `npm run test:unit-js` | 77-tool smoke, schema validation, auth ACL | No |
+| `npm run test:unit-js` | 81-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) |
@@ -777,7 +781,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.20.0 | **Tool Count:** 77 (verified LibreChat-compatible)
+**Version:** 0.21.0 | **Tool Count:** 81 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/actualToolsManager.js

@@ -10,6 +10,10 @@ const IMPLEMENTED_TOOLS = [
     'actual_accounts_create',
     'actual_accounts_delete',
     'actual_accounts_get_balance',
+    'actual_account_groups_list',
+    'actual_account_groups_create',
+    'actual_account_groups_update',
+    'actual_account_groups_delete',
     'actual_accounts_list',
     'actual_accounts_reopen',
     'actual_accounts_update',

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

@@ -5,7 +5,7 @@ import api from '@actual-app/api';
 // cannot expose its named exports via static import syntax. At runtime the default import
 // IS module.exports, so all methods are accessible as properties.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, importTransactions: rawImportTransactions, getTransactions: rawGetTransactions, getCategories: rawGetCategories, createCategory: rawCreateCategory, getPayees: rawGetPayees, getCommonPayees: rawGetCommonPayees, createPayee: rawCreatePayee, getBudgetMonths: rawGetBudgetMonths, getBudgetMonth: rawGetBudgetMonth, setBudgetAmount: rawSetBudgetAmount, createAccount: rawCreateAccount, updateAccount: rawUpdateAccount, getAccountBalance: rawGetAccountBalance, updateTransaction: rawUpdateTransaction, deleteTransaction: rawDeleteTransaction, updateCategory: rawUpdateCategory, deleteCategory: rawDeleteCategory, updatePayee: rawUpdatePayee, deletePayee: rawDeletePayee, deleteAccount: rawDeleteAccount, getRules: rawGetRules, createRule: rawCreateRule, updateRule: rawUpdateRule, deleteRule: rawDeleteRule, setBudgetCarryover: rawSetBudgetCarryover, closeAccount: rawCloseAccount, reopenAccount: rawReopenAccount, getCategoryGroups: rawGetCategoryGroups, createCategoryGroup: rawCreateCategoryGroup, updateCategoryGroup: rawUpdateCategoryGroup, deleteCategoryGroup: rawDeleteCategoryGroup, mergePayees: rawMergePayees, getPayeeRules: rawGetPayeeRules, batchBudgetUpdates: rawBatchBudgetUpdates, holdBudgetForNextMonth: rawHoldBudgetForNextMonth, resetBudgetHold: rawResetBudgetHold, runQuery: rawRunQuery, runBankSync: rawRunBankSync, getBudgets: rawGetBudgets, getIDByName: rawGetIDByName, getServerVersion: rawGetServerVersion, getSchedules: rawGetSchedules, createSchedule: rawCreateSchedule, updateSchedule: rawUpdateSchedule, deleteSchedule: rawDeleteSchedule, getTags: rawGetTags, createTag: rawCreateTag, updateTag: rawUpdateTag, deleteTag: rawDeleteTag, getNote: rawGetNote, updateNote: rawUpdateNote, exportBudget: rawExportBudget, importBudget: rawImportBudget, getPreferences: rawGetPreferences,
+const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, importTransactions: rawImportTransactions, getTransactions: rawGetTransactions, getCategories: rawGetCategories, createCategory: rawCreateCategory, getPayees: rawGetPayees, getCommonPayees: rawGetCommonPayees, createPayee: rawCreatePayee, getBudgetMonths: rawGetBudgetMonths, getBudgetMonth: rawGetBudgetMonth, setBudgetAmount: rawSetBudgetAmount, createAccount: rawCreateAccount, updateAccount: rawUpdateAccount, getAccountBalance: rawGetAccountBalance, updateTransaction: rawUpdateTransaction, deleteTransaction: rawDeleteTransaction, updateCategory: rawUpdateCategory, deleteCategory: rawDeleteCategory, updatePayee: rawUpdatePayee, deletePayee: rawDeletePayee, deleteAccount: rawDeleteAccount, getRules: rawGetRules, createRule: rawCreateRule, updateRule: rawUpdateRule, deleteRule: rawDeleteRule, setBudgetCarryover: rawSetBudgetCarryover, closeAccount: rawCloseAccount, reopenAccount: rawReopenAccount, getCategoryGroups: rawGetCategoryGroups, createCategoryGroup: rawCreateCategoryGroup, updateCategoryGroup: rawUpdateCategoryGroup, deleteCategoryGroup: rawDeleteCategoryGroup, mergePayees: rawMergePayees, getPayeeRules: rawGetPayeeRules, batchBudgetUpdates: rawBatchBudgetUpdates, holdBudgetForNextMonth: rawHoldBudgetForNextMonth, resetBudgetHold: rawResetBudgetHold, runQuery: rawRunQuery, runBankSync: rawRunBankSync, getBudgets: rawGetBudgets, getIDByName: rawGetIDByName, getServerVersion: rawGetServerVersion, getSchedules: rawGetSchedules, createSchedule: rawCreateSchedule, updateSchedule: rawUpdateSchedule, deleteSchedule: rawDeleteSchedule, getTags: rawGetTags, createTag: rawCreateTag, updateTag: rawUpdateTag, deleteTag: rawDeleteTag, getNote: rawGetNote, updateNote: rawUpdateNote, exportBudget: rawExportBudget, importBudget: rawImportBudget, getPreferences: rawGetPreferences, getAccountGroups: rawGetAccountGroups, createAccountGroup: rawCreateAccountGroup, updateAccountGroup: rawUpdateAccountGroup, deleteAccountGroup: rawDeleteAccountGroup,
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
  } = api;
 import { EventEmitter } from 'events';
@@ -3200,6 +3200,65 @@ export async function getServerVersion() {
     });
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
+/**
+ * Account groups (#429). Upstream added these in 26.9.0; the schema arrives through a
+ * migration SHIPPED IN `@actual-app/api` and applied to the LOCAL budget file, so these
+ * work against an older sync server too: the server relays messages and does not execute
+ * the queries.
+ *
+ * One semantic worth carrying into the tool descriptions, taken from upstream's own
+ * comment on the delete path: clearing member refs is best effort under CRDT sync, so a
+ * concurrent assignment on another device can win against those nulls. Consumers must
+ * treat an account whose `account_group_id` points at a missing or tombstoned group as
+ * UNGROUPED rather than as an error.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function getAccountGroups() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.account_groups.list').catch(() => { });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await withConcurrency(() => retry(() => rawGetAccountGroups(), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function createAccountGroup(group) {
+    observability.incrementToolCall('actual.account_groups.create').catch(() => { });
+    return queueWriteOperation(async () => {
+        const raw = await withConcurrency(() => retry(() => rawCreateAccountGroup(group), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
+        return normalizeToId(raw);
+        // Lands in account_groups only, so the four entity listings are untouched.
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
+}
+export async function updateAccountGroup(id, fields) {
+    observability.incrementToolCall('actual.account_groups.update').catch(() => { });
+    return queueWriteOperation(async () => {
+        // Read, decide and write inside ONE queued operation, so the existence check and the
+        // write are a single api-lock cycle and cannot be interleaved by a sibling (#371/#378).
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const groups = await withConcurrency(() => retry(() => rawGetAccountGroups(), { retries: 2, backoffMs: 200 }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (!groups.some((g) => g.id === id)) {
+            throw new NotFoundRefusal('Account group', id, 'actual_account_groups_list');
+        }
+        await withConcurrency(() => retry(() => rawUpdateAccountGroup(id, fields), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
+        // Renames the group row itself; no account row changes, so listings are preserved.
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
+}
+export async function deleteAccountGroup(id) {
+    observability.incrementToolCall('actual.account_groups.delete').catch(() => { });
+    return queueWriteOperation(async () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const groups = await withConcurrency(() => retry(() => rawGetAccountGroups(), { retries: 2, backoffMs: 200 }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (!groups.some((g) => g.id === id)) {
+            throw new NotFoundRefusal('Account group', id, 'actual_account_groups_list');
+        }
+        await withConcurrency(() => retry(() => rawDeleteAccountGroup(id), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
+        // NO preservesListings claim, deliberately: upstream's delete UPDATES every member
+        // account to null its account_group_id before removing the group, so the accounts
+        // listing CONTENT changes even though its id set does not. Claiming preservation here
+        // would serve a stale accounts listing to the next guard in the same drain.
+    });
+}
 export async function getTags() {
     return withActualApi(async () => {
         observability.incrementToolCall('actual.tags.get').catch(() => { });
@@ -3421,6 +3480,10 @@ export default {
     getPayees,
     getCommonPayees,
     createPayee,
+    getAccountGroups,
+    createAccountGroup,
+    updateAccountGroup,
+    deleteAccountGroup,
     getTags,
     createTag,
     updateTag,

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

@@ -52,6 +52,19 @@ export const ACTUAL_SCHEMA = {
         mask: { type: 'string' },
         bank: { type: 'id', ref: 'banks' },
         account_sync_source: { type: 'string' },
+        // #429: these four exist in upstream's ActualQL schema but were missing here, so
+        // actual_query_run rejected valid queries against them. account_group_id arrived with
+        // account groups in 26.9.0; the other three predate it and were simply never added.
+        account_group_id: { type: 'id', ref: 'account_groups' },
+        last_reconciled: { type: 'string' },
+        last_sync: { type: 'string' },
+        bank_sync_status: { type: 'string' },
+    },
+    account_groups: {
+        id: { type: 'id' },
+        name: { type: 'string', required: true },
+        sort_order: { type: 'float' },
+        tombstone: { type: 'boolean' },
     },
     categories: {
         id: { type: 'id' },

package/dist/src/lib/schemas/common.js

@@ -3,7 +3,7 @@
  *
  * Common validation schemas used across MCP tools for Actual Budget.
  * These schemas provide consistent validation, better error messages,
- * and reduce duplication across the 77 tool definitions.
+ * and reduce duplication across the 81 tool definitions.
  */
 import { z } from 'zod';
 import { MAX_NAME_LENGTH, MAX_NOTES_LENGTH, DATE_PATTERN, MONTH_PATTERN, UUID_PATTERN } from '../constants.js';
@@ -62,6 +62,14 @@ export const ruleIdSchema = z
  * Tag UUID validation
  * Used for: tag management operations (update, delete)
  */
+/**
+ * Account group UUID validation (#429)
+ * Used for: account group management operations (update, delete)
+ */
+export const accountGroupIdSchema = z
+    .string()
+    .regex(UUID_PATTERN, 'Invalid account group ID format (expected UUID)')
+    .describe('Account group UUID');
 export const tagIdSchema = z
     .string()
     .regex(UUID_PATTERN, 'Invalid tag ID format (expected UUID)')
@@ -225,6 +233,7 @@ export const CommonSchemas = {
     categoryGroupId: categoryGroupIdSchema,
     payeeId: payeeIdSchema,
     ruleId: ruleIdSchema,
+    accountGroupId: accountGroupIdSchema,
     tagId: tagIdSchema,
     scheduleId: scheduleIdSchema,
     // Dates

package/dist/src/lib/tool-annotations.js

@@ -55,6 +55,7 @@ const OPEN_WORLD = new Set(['actual_bank_sync']);
  *   actual_session_close   closes a pooled connection: server state, not budget data.
  */
 const READ_ONLY = new Set([
+    'actual_account_groups_list',
     'actual_account_flow_summary',
     'actual_recurring_expenses_summary',
     'actual_accounts_get_balance',
@@ -99,6 +100,7 @@ const READ_ONLY = new Set([
  * and in #357), so a close can be a delete.
  */
 const DESTRUCTIVE = new Set([
+    'actual_account_groups_delete',
     'actual_accounts_close',
     'actual_accounts_delete',
     // Upstream `reconcileTransactions` overwrites fields on transactions that ALREADY exist
@@ -151,6 +153,8 @@ const DESTRUCTIVE = new Set([
  * not, because on the split path it deletes and recreates child rows.
  */
 const ADDITIVE = new Set([
+    'actual_account_groups_create',
+    'actual_account_groups_update',
     'actual_accounts_create',
     'actual_accounts_reopen',
     'actual_accounts_update',

package/dist/src/tools/account_groups_create.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import adapter from '../lib/actual-adapter.js';
+/** #429: create a custom account group (Actual 26.9.0+). */
+export default createTool({
+    name: 'actual_account_groups_create',
+    description: 'Create a custom account group for organising accounts in the sidebar. ' +
+        'Returns the id of the new group. Assigning accounts to it is a separate step: ' +
+        'set the account\'s account_group_id with actual_accounts_update. ' +
+        'Requires an Actual server on 26.9.0 or newer.',
+    schema: z.object({
+        name: z.string().min(1).describe('Display name for the group, for example "Savings" or "Joint accounts"'),
+        sort_order: z
+            .number()
+            .optional()
+            .describe('Optional ordering position in the sidebar. Lower sorts first; omit to let Actual place it.'),
+    }),
+    handler: async (input) => {
+        const id = await adapter.createAccountGroup(input);
+        return { id, name: input.name };
+    },
+    examples: [
+        { description: 'Create a group for savings accounts', input: { name: 'Savings' } },
+        { description: 'Create a group pinned to the top of the sidebar', input: { name: 'Daily spending', sort_order: 0 } },
+    ],
+});

package/dist/src/tools/account_groups_delete.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
+import adapter from '../lib/actual-adapter.js';
+/** #429: delete a custom account group (Actual 26.9.0+). */
+export default createTool({
+    name: 'actual_account_groups_delete',
+    description: 'Delete a custom account group. The accounts in it are NOT deleted: they become ungrouped. ' +
+        'Note that upstream clears those member references best-effort under sync, so a concurrent ' +
+        'assignment on another device can survive the delete; treat any account still pointing at a ' +
+        'missing group as ungrouped. Refuses with a not-found error, writing nothing, when the group ' +
+        'does not exist. Requires an Actual server on 26.9.0 or newer.',
+    schema: z.object({
+        id: CommonSchemas.accountGroupId.describe('Id of the account group to delete (actual_account_groups_list lists them)'),
+    }),
+    handler: async (input) => {
+        await adapter.deleteAccountGroup(input.id);
+        return { success: true, id: input.id };
+    },
+    examples: [
+        { description: 'Delete a group, leaving its accounts ungrouped', input: { id: '00000000-0000-0000-0000-000000000000' } },
+    ],
+});

package/dist/src/tools/account_groups_list.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import adapter from '../lib/actual-adapter.js';
+/**
+ * #429: list the custom account groups (Actual 26.9.0+).
+ *
+ * Read the grouping semantics before relying on a group id: upstream clears member
+ * references on a best-effort basis under CRDT sync, so an account whose
+ * `account_group_id` points at a group that is missing here is UNGROUPED, not an error.
+ */
+export default createTool({
+    name: 'actual_account_groups_list',
+    description: 'List the custom account groups used to organise accounts in the sidebar. ' +
+        'Returns each group with its id, name and sort order. An account whose account_group_id ' +
+        'does not appear here is ungrouped: upstream clears member references best-effort under ' +
+        'sync, so a dangling reference is expected and is not an error. Requires an Actual server ' +
+        'on 26.9.0 or newer, which is where account groups were introduced.',
+    schema: z.object({}),
+    handler: async () => {
+        return await adapter.getAccountGroups();
+    },
+    examples: [{ description: 'List every account group', input: {} }],
+});

package/dist/src/tools/account_groups_update.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
+import adapter from '../lib/actual-adapter.js';
+/** #429: rename or reorder a custom account group (Actual 26.9.0+). */
+export default createTool({
+    name: 'actual_account_groups_update',
+    description: 'Rename a custom account group or change its sidebar position. ' +
+        'Does not change which accounts belong to it: use actual_accounts_update to move an ' +
+        'account between groups. Refuses with a not-found error, writing nothing, when the group ' +
+        'does not exist. Requires an Actual server on 26.9.0 or newer.',
+    schema: z.object({
+        id: CommonSchemas.accountGroupId.describe('Id of the account group to update (actual_account_groups_list lists them)'),
+        name: z.string().min(1).optional().describe('New display name'),
+        sort_order: z.number().optional().describe('New ordering position in the sidebar; lower sorts first'),
+    }),
+    handler: async (input) => {
+        const { id, ...fields } = input;
+        await adapter.updateAccountGroup(id, fields);
+        return { success: true, id, updated: Object.keys(fields) };
+    },
+    examples: [
+        { description: 'Rename a group', input: { id: '00000000-0000-0000-0000-000000000000', name: 'Long-term savings' } },
+    ],
+});

package/dist/src/tools/index.js

@@ -6,6 +6,10 @@ export { default as accounts_close } from './accounts_close.js';
 export { default as accounts_create } from './accounts_create.js';
 export { default as accounts_delete } from './accounts_delete.js';
 export { default as accounts_get_balance } from './accounts_get_balance.js';
+export { default as account_groups_list } from './account_groups_list.js';
+export { default as account_groups_create } from './account_groups_create.js';
+export { default as account_groups_update } from './account_groups_update.js';
+export { default as account_groups_delete } from './account_groups_delete.js';
 export { default as accounts_list } from './accounts_list.js';
 export { default as accounts_reopen } from './accounts_reopen.js';
 export { default as accounts_update } from './accounts_update.js';

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
   },
-  "description": "MCP server with 77 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
+  "description": "MCP server with 81 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
   "homepage": "https://github.com/agigante80/actual-mcp-server#readme",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/transactions_aggregate.test.js && node tests/unit/account_flow_summary.test.js && node tests/unit/recurring_expenses_summary.test.js && node tests/unit/generated_tools.smoke.test.js &&node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_hold_for_next_month.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/httpServer_init_failure_report.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_loader_import_allowlist.test.js && node tests/unit/budget_import_tracking.test.js && node tests/unit/pool_shutdown_under_lock.test.js && node tests/unit/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/transactions_update_splits.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/stdio_budget_switch.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/playwright_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budgets_import_syncid.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_identity_map.test.js && node tests/unit/budget_acl_userinfo.test.js && node tests/unit/acl_e2e_fixture_contract.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/transactions_aggregate.test.js && node tests/unit/account_flow_summary.test.js && node tests/unit/recurring_expenses_summary.test.js && node tests/unit/generated_tools.smoke.test.js &&node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/new_tool_completeness.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_hold_for_next_month.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/httpServer_init_failure_report.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_loader_import_allowlist.test.js && node tests/unit/budget_import_tracking.test.js && node tests/unit/pool_shutdown_under_lock.test.js && node tests/unit/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/transactions_update_splits.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/stdio_budget_switch.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/playwright_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budgets_import_syncid.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_identity_map.test.js && node tests/unit/budget_acl_userinfo.test.js && node tests/unit/acl_e2e_fixture_contract.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.test.js",
     "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
     "test:e2e": "npx playwright test",
     "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",