ynab-mcp-server

ynab-mcp-server

A Model Context Protocol (MCP) server built with mcp-framework. This MCP provides tools for interacting with your YNAB budgets setup at https://ynab.com

In order to have an AI interact with this tool, you will need to get your Personal Access Token from YNAB: https://api.ynab.com/#personal-access-tokens

The goal of the project is to be able to interact with my YNAB budget via an AI conversation. I'm going to start with read only actions and then work toward being able to make modifications to the budget as well.

Available tools:

• list all budgets
• Get specific budget
• Create a transaction

Next:

• fix so it isn't dependent on memories mcp, need to store account ids and category ids on initialization
• move money
• import transactions

Quick Start

# Install dependencies
npm install
 
# Build the project
npm run build

Project Structure

ynab-mcp-server/
├── src/
│   ├── tools/        # MCP Tools
│   │   └── ExampleTool.ts
│   └── index.ts      # Server entry point
├── package.json
└── tsconfig.json

Adding Components

The YNAB sdk describes the available api endpoints: https://github.com/ynab/ynab-sdk-js.

YNAB open api specification is here: https://api.ynab.com/papi/open_api_spec.yaml. This can be used to prompt an AI to generate a new tool. Example prompt for Cursor Agent:

create a new tool based on the readme and this openapi doc: https://api.ynab.com/papi/open_api_spec.yaml

The new tool should get the details for a single budget

You can add more tools using the CLI:

# Add a new tool
mcp add tool my-tool
 
# Example tools you might create:
mcp add tool data-processor
mcp add tool api-client
mcp add tool file-handler

Tool Development

Example tool structure:

import { MCPTool } from "mcp-framework";
import { z } from "zod";
 
interface MyToolInput {
  message: string;
}
 
class MyTool extends MCPTool<MyToolInput> {
  name = "my_tool";
  description = "Describes what your tool does";
 
  schema = {
    message: {
      type: z.string(),
      description: "Description of this input parameter",
    },
  };
 
  async execute(input: MyToolInput) {
    // Your tool logic here
    return `Processed: ${input.message}`;
  }
}
 
export default MyTool;

Publishing to npm

1. Update your package.json:
   • Ensure name is unique and follows npm naming conventions
   • Set appropriate version
   • Add description, author, license, etc.
   • Check bin points to the correct entry file
2. Build and test locally:

   npm run build
   npm link
   ynab-mcp-server  # Test your CLI locally
   

3. Login to npm (create account if necessary):

   npm login
   

4. Publish your package:

   npm publish
   

After publishing, users can add it to their claude desktop client (read below) or run it with npx

## Using with Claude Desktop

### Local Development

Add this configuration to your Claude Desktop config file:

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

```json
{
  "mcpServers": {
    "ynab-mcp-server": {
      "command": "node",
      "args":["/absolute/path/to/ynab-mcp-server/dist/index.js"]
    }
  }
}

After Publishing

Add this configuration to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ynab-mcp-server": {
      "command": "npx",
      "args": ["ynab-mcp-server"]
    }
  }
}

Building and Testing

1. Make changes to your tools
2. Run npm run build to compile
3. The server will automatically load your tools on startup

Learn More

• MCP Framework Github
• MCP Framework Docs