Metadata-Version: 2.4
Name: ynab-mcp-tools
Version: 0.1.0
Summary: An MCP server for the YNAB (You Need A Budget) API
Project-URL: Homepage, https://github.com/rgarcia/ynab-mcp-server
Project-URL: Repository, https://github.com/rgarcia/ynab-mcp-server
Project-URL: Issues, https://github.com/rgarcia/ynab-mcp-server/issues
Author: Rafael Garcia
License: MIT License
        
        Copyright (c) 2026 Rafael Garcia
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: mcp,model-context-protocol,ynab
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Requires-Dist: fastmcp>=3.4.4
Requires-Dist: httpx>=0.28.1
Requires-Dist: pyyaml>=6.0.3
Description-Content-Type: text/markdown

# YNAB MCP Server

An MCP (Model Context Protocol) server for the [YNAB (You Need A Budget)](https://www.ynab.com/) API, built with [FastMCP](https://gofastmcp.com/).

This server automatically exposes all YNAB API endpoints as MCP tools, allowing AI assistants like Claude to interact with your YNAB budgets, accounts, transactions, and more.

## Prerequisites

- [uv](https://docs.astral.sh/uv/) package manager
- A YNAB account with API access

## Setup

### Get Your YNAB API Token

1. Log in to your YNAB account at [app.ynab.com](https://app.ynab.com)
2. Go to **Account Settings** → **Developer Settings**
3. Click **New Token** under "Personal Access Tokens"
4. Give your token a name and click **Generate**
5. Copy the token (you won't be able to see it again!)

## Add the Server to Your MCP Client

The published package runs with `uvx ynab-mcp-tools`. `uvx` downloads it from
PyPI and runs it in an isolated environment, so you do not need to clone this
repository or manage a virtualenv.

### With Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ynab": {
      "command": "uvx",
      "args": ["ynab-mcp-tools"],
      "env": {
        "YNAB_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

### With Claude Code

Use [Claude Code](https://code.claude.com/docs/en/mcp)'s MCP CLI. The `--`
separates Claude's options from the server command.

For all projects (**user** scope):

```bash
claude mcp add ynab --scope user \
  -e "YNAB_API_TOKEN=your-token-here" \
  -- uvx ynab-mcp-tools
```

For the current directory only, omit `--scope user` or use `--scope local`. Use `claude mcp list` to verify and `claude mcp remove ynab --scope user` (or `local`) to uninstall.

### With Cursor

Add the following to your Cursor MCP settings (`~/.cursor/mcp.json` for global or `.cursor/mcp.json` in your project):

```json
{
  "mcpServers": {
    "ynab": {
      "command": "uvx",
      "args": ["ynab-mcp-tools"],
      "env": {
        "YNAB_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

### With OpenCode

Add the following to your OpenCode configuration file (`~/.config/opencode/opencode.json`):

```json
{
  "mcp": {
    "ynab": {
      "type": "local",
      "command": ["uvx", "ynab-mcp-tools"],
      "enabled": true,
      "environment": {
        "YNAB_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

## Available Tools

The server automatically exposes all YNAB API endpoints as MCP tools. Here are some of the available operations:

### User

- `getUser` - Get authenticated user information

### Budgets

- `getBudgets` - List all budgets
- `getBudgetById` - Get a single budget with all related entities
- `getBudgetSettingsById` - Get budget settings

### Accounts

- `getAccounts` - List all accounts for a budget
- `getAccountById` - Get a single account
- `createAccount` - Create a new account

### Categories

- `getCategories` - List all categories for a budget
- `getCategoryById` - Get a single category
- `updateCategory` - Update a category
- `getMonthCategoryById` - Get a category for a specific month
- `updateMonthCategory` - Update a category for a specific month

### Transactions

- `getTransactions` - List transactions
- `getTransactionById` - Get a single transaction
- `createTransaction` - Create a new transaction
- `updateTransaction` - Update a transaction
- `deleteTransaction` - Delete a transaction
- `importTransactions` - Import transactions
- `getTransactionsByAccount` - List transactions for an account
- `getTransactionsByCategory` - List transactions for a category
- `getTransactionsByPayee` - List transactions for a payee

### Payees

- `getPayees` - List all payees
- `getPayeeById` - Get a single payee
- `updatePayee` - Update a payee

### Scheduled Transactions

- `getScheduledTransactions` - List scheduled transactions
- `getScheduledTransactionById` - Get a single scheduled transaction
- `createScheduledTransaction` - Create a new scheduled transaction
- `updateScheduledTransaction` - Update a scheduled transaction

### Months

- `getBudgetMonths` - List budget months
- `getBudgetMonth` - Get a single budget month

## Example Usage

Once connected, you can ask Claude things like:

- "Show me my YNAB budgets"
- "What's my current balance in my checking account?"
- "List my transactions from last week"
- "Create a transaction for $50 at the grocery store"
- "How much have I spent on dining out this month?"

## Creating Custom Skills for Your YNAB Workflow

YNAB workflows are personal. Everyone has their own conventions for handling transactions, categorizing expenses, and managing duplicates. This repo includes a skill system that lets you encode your personal conventions so Claude can learn and apply them consistently.

### Step 1: Explore Your Budget

Start by asking Claude to do something useful with your YNAB data:

```
"Show me all my unapproved transactions"
"Help me categorize my uncategorized transactions"
"Find duplicate transactions in my budget"
```

Work through the task interactively. As you do, you'll naturally develop conventions. For example:

- "Venmo transactions always have a matching withdrawal in my checking account - I delete the Venmo one and keep the bank record"
- "Transactions from 'AMZN' should be categorized as 'Shopping' unless the memo mentions 'Kindle'"
- "Any transaction over $500 should be flagged for review"

### Step 2: Create a Skill to Encode Your Conventions

Once you've established patterns you want to reuse, create a skill to encode them. This repo includes the `skill-creator` skill in `.skills/skill-creator/` to help you build custom skills.

Ask Claude:

```
"Load the skill-creator skill and help me create a ynab skill that encodes
the conventions we just used for processing transactions"
```

The skill-creator will guide you through:

1. Identifying the reusable patterns from your workflow
2. Creating a SKILL.md file with your conventions
3. Structuring the skill for future use

### Step 3: Use Your Skills

Once created, your skills live in `.skills/` and Claude will automatically apply them when relevant. You can:

- Add more conventions as you discover them
- Share skills with others who have similar YNAB setups
- Build on the included examples

### Included Skills

- `.skills/skill-creator/` - Claude's official guide for creating new skills, included for convenience

## Resources

- [Development Guide](https://github.com/rgarcia/ynab-mcp-server/blob/main/DEVELOPMENT.md)
- [YNAB API Documentation](https://api.ynab.com/)
- [FastMCP Documentation](https://gofastmcp.com/)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)

## License

MIT
