YNAB预算数据MCP服务

YNAB MCP Server

A Model Context Protocol (MCP) server for the YNAB (You Need A Budget) API, enabling AI assistants like Claude to interact with your budget data.
Explore the docs »

Report Bug · Request Feature

About The Project

YNAB MCP is a Model Context Protocol server that exposes your YNAB budget data to AI assistants. It runs as a Docker container and is made publicly accessible via a Cloudflare Tunnel, allowing tools like Claude to query budgets, transactions, accounts, categories, and more over a streamable HTTP connection.

(back to top)

Built With

(back to top)

Getting Started

Prerequisites

• Docker and Docker Compose
• A YNAB Personal Access Token
• A Cloudflare Tunnel token (for remote access)

Installation

1. Clone the repo

   复制

   git clone https://github.com/Npab19/ynab-mcp.git
   cd ynab-mcp
   

2. Copy the example environment file and fill in your credentials

   复制

   cp .env.example .env
   

3. Edit .env with your credentials

   复制

   YNAB_API_KEY=your_ynab_personal_access_token_here
   Cloudflare_Token=your_cloudflare_tunnel_token_here
   MCP_BEARER_TOKEN=your_random_secret_token_here
   

   Generate a secure MCP_BEARER_TOKEN with:

   复制

   python -c "import secrets; print(secrets.token_urlsafe(32))"
   

4. Start the server

   复制

   docker compose up -d
   

The MCP server will be available at http://localhost:8000 locally, or via your Cloudflare Tunnel URL remotely.

Tip: A pre-built Docker image is published to the GitHub Container Registry on every push to master. You can use it instead of building locally by replacing build: . with image: ghcr.io/npab19/ynab-mcp:latest in docker-compose.yml.

(back to top)

Usage

The server requires authentication on all requests. The MCP_BEARER_TOKEN you set in .env is used to authenticate MCP clients.

Claude.ai web connectors (recommended)

Add a custom connector in Claude.ai settings with the URL:

https://<your-tunnel-url>/mcp?api_key=<MCP_BEARER_TOKEN>

This syncs across all your devices automatically.

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "ynab": {
      "type": "http",
      "url": "https://<your-tunnel-url>/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_BEARER_TOKEN>"
      }
    }
  }
}

Restart Claude Desktop after saving.

(back to top)

Available Tools

The server exposes tools across the following YNAB resource categories:

(back to top)

Roadmap

• [x] Streamable HTTP transport
• [x] Cloudflare Tunnel support
• [x] Core YNAB resource coverage (budgets, accounts, transactions, categories, months, payees, scheduled transactions)
• [x] Bearer token authentication (Authorization header + ?api_key query param)
• [x] Docker image published to GitHub Container Registry (GHCR)
• [ ] Write support (create/update transactions)
• [ ] Category budget assignment tools

See the open issues for a full list of proposed features and known issues.

(back to top)

Contributing

Contributions are welcome! If you have a suggestion, please fork the repo and create a pull request or open an issue with the tag "enhancement".

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Project Link: https://github.com/Npab19/ynab-mcp

(back to top)

Acknowledgments

• YNAB API Documentation
• Model Context Protocol
• Cloudflare Tunnel
• Img Shields
• Best-README-Template

(back to top)