@oliverames/ynab-mcp-server 2.1.0 → 3.0.0

package/README.md

@@ -2,29 +2,29 @@
   <img src="assets/icon.png" width="80" height="80" alt="YNAB">
 </p>
 
-<h1 align="center">YNAB MCP Server</h1>
+<h1 align="center">MCP Server for YNAB</h1>
 
 <p align="center">
-  <strong>The complete Model Context Protocol server for YNAB</strong><br>
+  <strong>A local Model Context Protocol server for YNAB budget operations</strong><br>
   <em>Give your AI assistant read-only budget access by default, with explicit write opt-in</em>
 </p>
 
 <p align="center">
   <code>47 tools with writes enabled</code> &bull;
-  <code>100% API coverage</code> &bull;
-  <code>YNAB API v1.83</code>
+  <code>YNAB API v1.85</code> &bull;
+  <code>read-only by default</code>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@oliverames/ynab-mcp-server"><img src="https://img.shields.io/npm/v/%40oliverames%2Fynab-mcp-server?style=flat-square&color=f5a542" alt="npm"></a>
-  <a href="https://github.com/oliverames/ynab-mcp-server/releases/tag/v2.1.0"><img src="https://img.shields.io/github/v/release/oliverames/ynab-mcp-server?style=flat-square&color=f5a542&label=MCPB" alt="MCPB release"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-f5a542?style=flat-square" alt="License"></a>
   <a href="https://www.buymeacoffee.com/oliverames"><img src="https://img.shields.io/badge/Buy_Me_a_Coffee-support-f5a542?style=flat-square&logo=buy-me-a-coffee&logoColor=white" alt="Buy Me a Coffee"></a>
 </p>
 
 <p align="center">
   <a href="#quick-start">Quick Start</a> &bull;
-  <a href="#install-with-mcpb">MCPB Download</a> &bull;
+  <a href="#install-in-claude-code">Claude Code</a> &bull;
+  <a href="#install-in-codex">Codex</a> &bull;
   <a href="#what-you-can-do">What You Can Do</a> &bull;
   <a href="#tools-reference">Tools Reference</a> &bull;
   <a href="#environment-variables">Configuration</a>
@@ -36,25 +36,119 @@
 
 YNAB's budgeting philosophy works best when you interact with your budget frequently - but the app interface isn't designed for quick queries or bulk operations. "How much did I spend on groceries this month?" shouldn't require navigating three screens. "Categorize all my Amazon orders from this week" shouldn't be a manual, one-by-one process.
 
-This server gives your AI assistant a safe interface to YNAB's API, turning natural language into budget review and, when explicitly enabled, budget operations. All monetary values are automatically converted between dollars and YNAB's internal milliunits format so the AI never has to think about it. Built on the [official YNAB JavaScript SDK](https://github.com/ynab/ynab-sdk-js) with direct API calls for the newest endpoints (category creation, category groups, money movements) that the SDK hasn't caught up with yet.
+This server gives your AI assistant a safe local interface to YNAB's API, turning natural language into budget review and, when explicitly enabled, budget operations. All monetary values are automatically converted between dollars and YNAB's internal milliunits format so the AI never has to think about it. Built on the [official YNAB JavaScript SDK](https://github.com/ynab/ynab-sdk-js) with direct API calls for endpoints and query parameters that the SDK has not caught up with yet.
 
 ---
 
 ## Quick Start
 
-### Install with MCPB
+This package stands on its own as a stdio MCP server. You do not need a Claude or Codex marketplace plugin; install it directly with `npx` and your MCP client will launch it on demand.
 
-For Claude Desktop and other MCPB-compatible clients, download the local bundle from the [v2.0.0 release](https://github.com/oliverames/ynab-mcp-server/releases/tag/v2.1.0):
+### 1. Get a YNAB Personal Access Token
 
-[Download `ynab-mcp-server-2.1.0.mcpb`](https://github.com/oliverames/ynab-mcp-server/releases/download/v2.1.0/ynab-mcp-server-2.1.0.mcpb)
+Go to [YNAB Developer Settings](https://app.ynab.com/settings/developer) and create a new personal access token.
 
-The bundle includes the YNAB favicon, production runtime dependencies, and setup prompts for your personal access token, optional default budget ID, and optional write-tool opt-in.
+This local stdio package is intended for a YNAB account owner running the server for their own account. A public hosted connector for other YNAB users must use YNAB OAuth instead of asking users for personal access tokens; see [docs/hosted-oauth-connector.md](docs/hosted-oauth-connector.md).
 
-### 1. Get a YNAB Personal Access Token
+Credential lookup order:
 
-Go to [YNAB Developer Settings](https://app.ynab.com/settings/developer) and create a new personal access token.
+1. Values passed directly to the MCP process, such as `YNAB_API_TOKEN`.
+2. Codex plaintext settings in `~/.codex/config.toml`, first `[shell_environment_policy.set]`, then `[mcp_servers.ynab.env]`.
+3. Claude Code plaintext settings in `~/.claude/settings.json` under top-level `env`.
+4. `YNAB_API_TOKEN_FILE`, if configured in any of the sources above.
+5. `YNAB_OP_PATH`, if configured in any of the sources above and the `op` CLI is available.
+
+If no token is found, `ynab_auth_status` returns a structured setup guide. Agents should first ask whether the user already has the YNAB token in a password manager such as 1Password. If yes, ask permission before configuring `YNAB_OP_PATH`; otherwise ask the user to add `YNAB_API_TOKEN` to the correct Codex or Claude config file and restart the MCP server.
+
+### 2. Install in Claude Code
+
+Use user scope if you want the server available in all Claude Code projects:
+
+```bash
+claude mcp add ynab --scope user \
+  -e YNAB_API_TOKEN=your-token-here \
+  -- npx -y @oliverames/ynab-mcp-server@latest
+```
+
+Add a default budget ID if you do not want tools to use YNAB's `last-used` budget:
+
+```bash
+claude mcp add ynab --scope user \
+  -e YNAB_API_TOKEN=your-token-here \
+  -e YNAB_BUDGET_ID=optional-default-budget-id \
+  -- npx -y @oliverames/ynab-mcp-server@latest
+```
+
+Use `--scope project` instead of `--scope user` if you want Claude Code to write a project-local `.mcp.json`.
+
+If `~/.claude/settings.json` already contains `env.YNAB_API_TOKEN`, you may omit `-e YNAB_API_TOKEN=...`; the server will read the Claude setting as a fallback if the launcher does not inject it.
+
+Verify Claude Code can see the server:
+
+```bash
+claude mcp get ynab
+```
+
+If Claude Code reports that `ynab` already exists, remove the old entry and run the add command again:
+
+```bash
+claude mcp remove ynab
+```
+
+### 3. Install in Codex
+
+Register the same npm package directly with Codex:
+
+```bash
+codex mcp add ynab \
+  --env YNAB_API_TOKEN=your-token-here \
+  -- npx -y @oliverames/ynab-mcp-server@latest
+```
+
+With a default budget ID:
+
+```bash
+codex mcp add ynab \
+  --env YNAB_API_TOKEN=your-token-here \
+  --env YNAB_BUDGET_ID=optional-default-budget-id \
+  -- npx -y @oliverames/ynab-mcp-server@latest
+```
+
+If `~/.codex/config.toml` already contains `YNAB_API_TOKEN` under `[shell_environment_policy.set]` or `[mcp_servers.ynab.env]`, you may omit `--env YNAB_API_TOKEN=...`; the server will read the Codex setting as a fallback if the launcher does not inject it.
+
+Verify Codex can see the server:
+
+```bash
+codex mcp get ynab
+```
+
+If Codex reports that `ynab` already exists, remove the old entry and run the add command again:
+
+```bash
+codex mcp remove ynab
+```
+
+### 4. Enable Write Tools (Optional)
 
-### 2. Configure your MCP client
+By default, the server registers read-only tools only. To expose tools that create, update, import, or delete YNAB data, add `YNAB_ALLOW_WRITES=1` when you register the server:
+
+```bash
+claude mcp add ynab --scope user \
+  -e YNAB_API_TOKEN=your-token-here \
+  -e YNAB_ALLOW_WRITES=1 \
+  -- npx -y @oliverames/ynab-mcp-server@latest
+```
+
+```bash
+codex mcp add ynab \
+  --env YNAB_API_TOKEN=your-token-here \
+  --env YNAB_ALLOW_WRITES=1 \
+  -- npx -y @oliverames/ynab-mcp-server@latest
+```
+
+Bulk-filter write tools such as `approve_transactions`, `reassign_payee_transactions`, and the generic `ynab_write_tool_execute` helper also require `confirmed: true` in the tool input after explicit user confirmation. For extra protection, pass `expectedMatchedCount` when using bulk-filter writes.
+
+### Manual JSON Config
 
 **Claude Desktop** (`claude_desktop_config.json`):
 
@@ -72,7 +166,7 @@ Go to [YNAB Developer Settings](https://app.ynab.com/settings/developer) and cre
 }
 ```
 
-**Claude Code** (`.mcp.json`):
+**Generic MCP client**:
 
 ```json
 {
@@ -88,7 +182,7 @@ Go to [YNAB Developer Settings](https://app.ynab.com/settings/developer) and cre
 }
 ```
 
-Or install globally and point to the binary directly:
+If you prefer a global install, point your MCP client at the package binary directly:
 
 ```bash
 npm install -g @oliverames/ynab-mcp-server
@@ -98,7 +192,7 @@ npm install -g @oliverames/ynab-mcp-server
 {
   "mcpServers": {
     "ynab": {
-      "command": "ynab-mcp-server",
+      "command": "mcp-server-for-ynab",
       "env": {
         "YNAB_API_TOKEN": "your-token-here",
         "YNAB_BUDGET_ID": "optional-default-budget-id"
@@ -108,23 +202,28 @@ npm install -g @oliverames/ynab-mcp-server
 }
 ```
 
-That's it. Your AI can now talk to YNAB.
+### 1Password Token Lookup (Optional)
 
-By default, the server registers read-only tools only. To expose tools that create, update, import, or delete YNAB data, add `YNAB_ALLOW_WRITES=1` to the MCP server environment:
+If your token is stored in 1Password, set `YNAB_OP_PATH` instead of `YNAB_API_TOKEN`. The `op` CLI must be installed and authenticated in the environment that launches the MCP server.
 
-```json
-{
-  "mcpServers": {
-    "ynab": {
-      "command": "npx",
-      "args": ["-y", "@oliverames/ynab-mcp-server"],
-      "env": {
-        "YNAB_API_TOKEN": "your-token-here",
-        "YNAB_ALLOW_WRITES": "1"
-      }
-    }
-  }
-}
+```bash
+claude mcp add ynab --scope user \
+  -e YNAB_OP_PATH="op://Personal/YNAB API Token/credential" \
+  -- npx -y @oliverames/ynab-mcp-server@latest
+```
+
+```bash
+codex mcp add ynab \
+  --env 'YNAB_OP_PATH=op://Personal/YNAB API Token/credential' \
+  -- npx -y @oliverames/ynab-mcp-server@latest
+```
+
+### Local Smoke Test
+
+From this repo, you can verify the published npm package without changing any MCP client config:
+
+```bash
+YNAB_API_TOKEN=your-token-here npm run smoke:review-unapproved -- --published
 ```
 
 ---
@@ -148,7 +247,7 @@ By default, the server registers read-only tools only. To expose tools that crea
 
 ## Features
 
-**Complete YNAB API v1.83 coverage** with 47 tools when writes are enabled:
+**YNAB API v1.85 coverage** with 47 tools when writes are enabled:
 
 | Resource | Tools | Capabilities |
 |----------|-------|-------------|
@@ -169,13 +268,14 @@ By default, the server registers read-only tools only. To expose tools that crea
 - **Dollar amounts everywhere** - inputs and outputs are in dollars (`-12.34`), never milliunits (`-12340`). Conversion is automatic and transparent.
 - **Smart budget resolution** - set `YNAB_BUDGET_ID` for a default, or omit it to auto-resolve to your last-used budget. Every tool accepts an optional `budgetId` override.
 - **Pinned YNAB host** - all HTTP requests are restricted to `https://api.ynab.com`, redirects are not followed, and API tokens are redacted from surfaced errors.
-- **Token fallback options** - use `YNAB_API_TOKEN`, a small token file via `YNAB_API_TOKEN_FILE`, or a 1Password CLI reference via `YNAB_OP_PATH`.
+- **Agent-aware token fallback** - use direct process env, Codex `~/.codex/config.toml`, Claude `~/.claude/settings.json`, a small token file via `YNAB_API_TOKEN_FILE`, or a 1Password CLI reference via `YNAB_OP_PATH`.
 - **Split transactions** - first-class support for subtransactions in create, read, and format operations.
+- **Current transaction filters** - transaction list tools support `sinceDate`, `untilDate`, type filters, resource filters, and delta requests. YNAB defaults omitted `sinceDate` to one year ago, so pass an explicit older date when you need older history.
 - **Bulk operations** - `create_transactions` and `update_transactions` handle arrays in a single API call.
 - **Verified batch updates** - `update_transactions` refetches every requested transaction after the bulk API call, retries mismatched fields once through `update_transaction`, and returns a `verification` block so approval counts cannot hide failed category writes.
 - **Fetch-then-merge updates** - scheduled transaction updates (which use PUT semantics) automatically fetch the current state and merge your changes, so you only specify what changed.
 - **Fuzzy search** - `search_categories` and `search_payees` do case-insensitive partial matching across all entries.
-- **Approval workflow with anomaly flags** - `review_unapproved` groups transactions into "ready to approve" (categorized, split, or transfer) and "needs attention" (uncategorized), and attaches a `flags` array to each transaction surfacing anomalies: `manually_entered` (not bank-imported), `match_broken` (stale match reference), `scheduled_transaction_realized`, `new_payee`, `no_prior_amount_match` (novel amount for this payee), and `category_drift:was_X` (payee categorized differently in the prior 60 days). Group-level flags aggregate the union of all transaction flags.
+- **Approval workflow with anomaly flags** - `review_unapproved` groups transactions into "ready to approve" (categorized, split, or transfer) and "needs attention" (uncategorized), and attaches a `flags` array to each transaction surfacing anomalies: `manually_entered` (not bank-imported), `match_broken` (stale match reference), `scheduled_transaction_realized`, `new_payee`, `no_prior_amount_match` (novel amount for this payee), and `category_drift:was_X` (payee categorized differently in the prior 60 days). Group-level flags aggregate the union of all transaction flags. Bulk approval requires `confirmed: true`.
 - **Nullable updates** - update tools accept `null` for clearable fields (`memo`, `payeeName`, `categoryId`, `flagColor`) to distinguish "don't change" (omit) from "clear this field" (`null`).
 - **Target behavior support** - category create/update tools expose `goalNeedsWholeAmount` for YNAB's "Set aside another" vs. "Refill up to" goal behavior.
 - **Delta request support** - high-volume list tools accept `lastKnowledgeOfServer` and return `server_knowledge` when that parameter is provided.
@@ -258,14 +358,14 @@ Read tools are available by default. Tools that create, update, import, or delet
 
 | Tool | Description |
 |------|-------------|
-| `get_transactions` | Get transactions with filters: by account, category, payee, month, or status (`unapproved`/`uncategorized`) |
+| `get_transactions` | Get transactions with filters: by account, category, payee, month, status (`unapproved`/`uncategorized`), `sinceDate`, and `untilDate` |
 | `get_transaction` | Get a single transaction by ID (includes subtransactions). Auto-handles composite scheduled-transaction IDs like `uuid_YYYY-MM-DD`; if the underlying matched transaction has been deleted, falls back to returning the active scheduled template wrapped as `{ resource_type: "scheduled_transaction", ... }`. |
 | `create_transaction` | Write tool: create a transaction with optional split (subtransactions must sum to total) |
 | `create_transactions` | Write tool: bulk create multiple transactions in a single API call (supports split transactions) |
 | `update_transaction` | Write tool: partial update - only specified fields change |
 | `update_transactions` | Write tool: batch update multiple transactions at once, then refetch and verify requested fields persisted. Pass `returnSummary: true` for compact counts instead of full objects on large batches (avoids overflowing the tool-result size limit). |
-| `approve_transactions` | Write tool: approve unapproved transactions in bulk by filter (`payeeId` / `categoryId` / `accountId`) without hand-listing IDs. Skips uncategorized transactions by default; returns a compact summary. |
-| `reassign_payee_transactions` | Write tool: move all transactions from one payee to another — the merge workaround, since the YNAB API has no payee delete/merge endpoint. |
+| `approve_transactions` | Write tool: approve unapproved transactions in bulk by filter (`payeeId` / `categoryId` / `accountId`) without hand-listing IDs. Skips uncategorized transactions by default, requires `confirmed: true`, and supports `expectedMatchedCount`. |
+| `reassign_payee_transactions` | Write tool: move all transactions from one payee to another, the merge workaround since the YNAB API has no payee delete/merge endpoint. Requires `confirmed: true` and supports `expectedMatchedCount`. |
 | `delete_transaction` | Write tool: delete a transaction |
 | `import_transactions` | Write tool: trigger import from linked bank accounts |
 
@@ -298,6 +398,18 @@ The server starts in read-only mode. Write tools are not merely discouraged; the
 
 If a client already has the process running, changing the environment is not enough. Restart the MCP server after setting or clearing `YNAB_ALLOW_WRITES`.
 
+Bulk-filter writes require confirmation in the tool input, not only in surrounding chat:
+
+```json
+{
+  "confirmed": true,
+  "expectedMatchedCount": 3,
+  "payeeId": "payee-id-to-approve"
+}
+```
+
+If `expectedMatchedCount` is provided and the current match count differs, the tool returns an error before mutating any transactions.
+
 ### Batch Updates
 
 When a batch operation categorizes and approves transactions at the same time, do not use `review_unapproved` counts as the only success check. Approved transactions leave the review queue even if a category write failed, so queue counts can hide approved-but-still-uncategorized transactions.
@@ -328,17 +440,18 @@ Manual YNAB transfer fixes can replace one side of the pair with a new transacti
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `YNAB_API_TOKEN` | Yes* | [Personal access token](https://app.ynab.com/settings/developer) from YNAB Developer Settings. |
-| `YNAB_API_TOKEN_FILE` | No | Path to a file containing the token. The file must be 4 KB or smaller. Used only when `YNAB_API_TOKEN` is unset. |
+| `YNAB_API_TOKEN` | Yes* | [Personal access token](https://app.ynab.com/settings/developer) from YNAB Developer Settings. Read from process env first, then Codex and Claude plaintext agent settings. |
+| `YNAB_API_TOKEN_FILE` | No | Path to a file containing the token. The file must be 4 KB or smaller. Used only when `YNAB_API_TOKEN` is unset. Can be provided through process env or agent settings. |
 | `YNAB_BUDGET_ID` | No | Default budget ID. If omitted, uses `"last-used"` (your most recently accessed budget). Run `list_budgets` to find IDs. |
 | `YNAB_ALLOW_WRITES` | No | Set to `1` to register write tools. Any other value keeps the server read-only. |
-| `YNAB_OP_PATH` | No | 1Password secret reference for your API token (see below). Required only if using the 1Password fallback instead of `YNAB_API_TOKEN`. |
+| `YNAB_OP_PATH` | No | 1Password secret reference for your API token (see below). Required only if using the 1Password fallback instead of `YNAB_API_TOKEN`. Can be provided through process env or agent settings. |
+| `YNAB_DISABLE_AGENT_CONFIG_FALLBACK` | No | Set to `1` to stop the server from reading `~/.codex/config.toml` and `~/.claude/settings.json`. Intended for tests and tightly controlled runtimes. |
 | `YNAB_RATE_LIMIT_PER_HOUR` | No | Client-side rate limiter. Defaults to `190`; set to `0` to disable for controlled tests. |
 | `YNAB_RATE_LIMIT_BURST` | No | Maximum burst size before rate limiting pauses requests. Defaults to `10`. |
 | `YNAB_HTTP_TIMEOUT_MS` | No | Per-request timeout. Defaults to `30000`. |
 | `YNAB_MAX_RESPONSE_BYTES` | No | Maximum direct-fetch response size for newer endpoints. Defaults to `8388608`. |
 
-*`YNAB_API_TOKEN` is required unless `YNAB_API_TOKEN_FILE` or `YNAB_OP_PATH` is set.
+*`YNAB_API_TOKEN` is required unless `YNAB_API_TOKEN_FILE` or `YNAB_OP_PATH` is set. These values may come from direct process env, Codex config, or Claude settings.
 
 ### 1Password Integration
 
@@ -358,7 +471,7 @@ If you store your YNAB token in [1Password CLI](https://developer.1password.com/
 }
 ```
 
-The fallback adds ~1-2s to startup and is silently skipped if `op` is unavailable or the item is not found.
+The fallback adds ~1-2s to startup and is silently skipped if `op` is unavailable or the item is not found. If no token source is configured, `ynab_auth_status` tells the calling agent to ask whether you have a token in 1Password or another password manager, request permission before editing agent config, and otherwise ask you to add `YNAB_API_TOKEN` to the appropriate Codex or Claude settings file.
 
 ---
 
@@ -387,20 +500,21 @@ Set `YNAB_RATE_LIMIT_PER_HOUR=0` only for controlled local tests or smoke checks
 
 ```
 ┌─────────────────────┐     ┌──────────────────┐     ┌──────────────┐
-│  AI Assistant       │────▶│  YNAB MCP Server │────▶│  YNAB API    │
-│  (Claude, GPT, etc) │◀────│  (this package)  │◀────│  api.ynab.com│
+│  AI Assistant       │────▶│ MCP Server for   │────▶│  YNAB API    │
+│                     │     │ YNAB             │     │              │
+│  (Claude, GPT, etc) │◀────│ (this package)   │◀────│  api.ynab.com│
 └─────────────────────┘     └──────────────────┘     └──────────────┘
          MCP                    stdio transport           HTTPS/REST
 ```
 
 - **Transport:** stdio (standard MCP server pattern)
-- **Auth:** Bearer token via `YNAB_API_TOKEN`, `YNAB_API_TOKEN_FILE`, or `YNAB_OP_PATH`
-- **SDK:** Official [`ynab`](https://www.npmjs.com/package/ynab) v2.5+ for core endpoints, direct `fetch` for newer API features
+- **Auth:** Bearer token via `YNAB_API_TOKEN`, `YNAB_API_TOKEN_FILE`, or `YNAB_OP_PATH` for local owner-run use
+- **SDK:** Official [`ynab`](https://www.npmjs.com/package/ynab) v4.1+ for core endpoints, direct `fetch` for newer API features and v1.85 transaction filters
 - **Safety:** read-only default, explicit write opt-in, host-pinned HTTPS requests to `api.ynab.com`, no redirect following, redacted token errors
 - **Validation:** All parameters validated with [Zod](https://zod.dev) schemas
 - **Error handling:** API errors are caught, formatted, and returned as MCP error responses with detail messages
 
-For a hosted OAuth connector design, see [docs/hosted-oauth-connector.md](docs/hosted-oauth-connector.md).
+For a hosted OAuth connector design, see [docs/hosted-oauth-connector.md](docs/hosted-oauth-connector.md). For data handling details for this local package, see [docs/privacy.md](docs/privacy.md).
 
 ---
 
@@ -418,7 +532,7 @@ Tests cover all tool categories: reads, reversible writes, bulk operations, sear
 
 ### MCP Smoke Tests
 
-Use the smoke tests when you need to prove the server is reachable over stdio without reconstructing a custom MCP client. These commands use the official MCP SDK client, the same transport shape used by normal MCP hosts, and require `YNAB_API_TOKEN` because this server validates credentials at startup.
+Use the smoke tests when you need to prove the server is reachable over stdio without reconstructing a custom MCP client. These commands use the official MCP SDK client, the same transport shape used by normal MCP hosts. `smoke:list-tools` can run without a live token to verify discovery, but live read and write smokes require `YNAB_API_TOKEN`, `YNAB_API_TOKEN_FILE`, or `YNAB_OP_PATH`.
 
 ```bash
 YNAB_API_TOKEN=your-token YNAB_BUDGET_ID=your-budget-id npm run smoke:list-tools
@@ -460,11 +574,20 @@ Before publishing, run:
 
 ```bash
 npm run release:check
-npm run build:mcpb
 npm pack --dry-run
 ```
 
-After publishing, run `npm run release:check:registry` to verify the npm `latest` dist-tag, repo metadata, README release links, and MCPB artifact references all agree on the same version.
+After publishing, run `npm run release:check:registry` to verify the npm `latest` dist-tag and repo metadata agree on the same version. `npm run build:mcpb` remains available for an explicit local bundle, but the normal install path is direct MCP registration through npm.
+
+---
+
+## Privacy and Non-Affiliation
+
+See [docs/privacy.md](docs/privacy.md) for this connector's data handling, deletion, and token-use details.
+
+This connector is not affiliated, associated, or in any way officially connected with YNAB or any of its subsidiaries or affiliates. The official YNAB website can be found at [https://www.ynab.com](https://www.ynab.com/).
+
+The names YNAB and You Need A Budget, as well as related names, trade names, marks, trademarks, emblems, and images are registered trademarks of YNAB.
 
 ---
 

package/docs/privacy.md

@@ -0,0 +1,51 @@
+# Privacy Policy for MCP Server for YNAB
+
+Last Updated: June 8, 2026
+
+MCP Server for YNAB is a local stdio MCP server that runs on the user's machine or in a user-controlled MCP host. It connects the user's MCP client to the YNAB API.
+
+## Data Access
+
+The server can access YNAB budget data that the configured YNAB access token is allowed to access, including budgets, accounts, categories, payees, transactions, scheduled transactions, months, and related metadata.
+
+Write tools are disabled by default. They are registered only when `YNAB_ALLOW_WRITES=1` is set before the MCP process starts. Bulk-filter write tools also require `confirmed: true` in the tool input after explicit user confirmation.
+
+## Data Storage
+
+This package does not create a database and does not store YNAB budget data outside the running MCP process. It returns YNAB API responses to the connected MCP client so the client can answer the user's request.
+
+Authentication is configured by the user through one of these local mechanisms:
+
+- `YNAB_API_TOKEN`
+- `YNAB_API_TOKEN_FILE`
+- `YNAB_OP_PATH`
+- Codex local plaintext settings in `~/.codex/config.toml`
+- Claude Code local plaintext settings in `~/.claude/settings.json`
+
+The server does not ask for, handle, or store bank credentials or other financial account login credentials.
+
+## Data Sharing
+
+This package sends YNAB API requests only to `https://api.ynab.com`. Outbound API requests are host-pinned to `api.ynab.com`, HTTPS-only, and redirects are not followed.
+
+The package does not sell YNAB user data and does not intentionally share YNAB user data with third parties. The connected MCP host and AI assistant may receive tool results because that is the purpose of the MCP connection; users should review their MCP host's own privacy and retention policies.
+
+## Logs and Diagnostics
+
+The server redacts bearer tokens and authorization headers from surfaced errors. Users should still avoid pasting tokens, budget exports, or sensitive transaction details into public issues or support requests.
+
+## Deleting Data
+
+Because this local package does not persist YNAB budget data, there is no server-side data store to delete. To stop future access:
+
+1. Remove the MCP server from the MCP host configuration.
+2. Delete any local token file or environment variable used for `YNAB_API_TOKEN`.
+3. Revoke the personal access token in YNAB Developer Settings.
+
+If a hosted OAuth connector is deployed later, that hosted service must publish its own privacy policy, token storage details, and user-facing deletion or revocation flow.
+
+## Non-Affiliation
+
+This connector is not affiliated, associated, or in any way officially connected with YNAB or any of its subsidiaries or affiliates. The official YNAB website can be found at https://www.ynab.com/.
+
+The names YNAB and You Need A Budget, as well as related names, trade names, marks, trademarks, emblems, and images are registered trademarks of YNAB.