MCP Ynab Server

🚀 MCP YNAB Server

An MCP server implementation that provides access to YNAB (You Need A Budget) functionality via the Model Context Protocol (MCP).

✨ Features

• View account balances and transactions.
• Create new transactions.
• Access YNAB data through standardized MCP resources.

📦 Installation

uv pip install -e .

📚 Configuration

This server requires a YNAB API key to run. You can obtain it from your YNAB Developer Settings.

The API key can be provided in the following ways:

1. Environment variable: YNAB_API_KEY=your_api_key
2. MCP secret management system
3. .env file in the project root directory

💻 Usage Examples

🚀 Run the Server

# Development mode with hot reloading and browser launch
task dev

# Production installation for Claude Desktop, Goose, or other MCP - supported environments
task install

📜 Available Resources

• ynab://accounts - List all YNAB accounts.
• ynab://transactions/{account_id} - Get recent transactions for a specific account.

🛠️ Available Tools

• create_transaction - Create a new transaction.
• get_account_balance - Get the current balance of an account.

💻 Basic Usage

# Create a new transaction
result = await create_transaction(
    account_id="your_account_id",
    amount=42.50,  # Amount in US dollars
    payee_name="Coffee Shop",
    category_name="Dining Out",
    memo="Morning coffee"
)

# Get account balance
balance = await get_account_balance("your_account_id")

# List accounts
accounts = await ctx.read_resource("ynab://accounts")

# Get recent transactions
transactions = await ctx.read_resource(f"ynab://transactions/{account_id}")

🔧 Development

# Install dependencies (using uv)
task deps

# Run all tests, including integration tests (requires YNAB API key)
task test:all

# Generate coverage report
task coverage

# Format and check code
task fmt  # This should be added to the Taskfile

📋 Project Tasks

This project uses a Taskfile to manage common operations. Key commands include:

task dev       # Run the development server with automatic reloading
task test      # Run unit tests
task coverage  # Generate test coverage report
task install   # Install the production version
task deps      # Synchronize dependencies

See Taskfile.yml for all available tasks.