Ynab MCP Server

🚀 ynab-mcp-server

A Model Context Protocol (MCP) server built with the mcp-framework. This MCP provides tools to interact with YNAB budgets, available at https://ynab.com.

To enable AI interaction with this tool, you need to obtain your personal access token: Get it from YNAB at https://api.ynab.com/#personal-access-tokens. When adding this MCP server to any client, you need to provide your personal access token as YNAB_API_TOKEN. This token is never sent directly to the LLM. It is privately stored as an environment variable and is only used to call the YNAB API.

🚀 Quick Start

✨ Features

• Budget Data Import: Import budget data from YNAB and parse it into an MCP-compatible format.
• Data Query: Support complex queries on budget data, such as filtering by category, time range, etc.
• Operation Feedback: Provide real-time feedback on operation results based on user instructions.

📦 Installation

1. Clone the repository:

git clone https://github.com/your-repository.git
cd ynab-mcp-server

2. Install dependencies:

npm install

3. Start the server:

node dist/index.js

💻 Usage Examples

Basic Usage

First, set up the environment variables:

• YNAB_API_TOKEN (Required)
• YNAB_BUDGET_ID (Optional)

First-time Setup

• Prompt to select the budget you own. If not configured before using other tools, it will automatically guide you through the process.
• Provide YNAB_API_TOKEN and YNAB_BUDGET_ID in the environment variables.

📚 Documentation

Project Structure

Core Files

• index.js: The entry file responsible for initializing the MCP server.
• config.js: Configure environment variables and default values.
• tools/: Contains specific tool modules for implementation.

Tool Implementations

Budget Data Import (ynab.ts)

export async function fetchBudgetData(token: string, budgetId?: string) {
    // 实现从 YNAB 获取预算数据的逻辑
}

Data Query (query.ts)

export interface QueryOptions {
    category?: string;
    startDate?: string;
    endDate?: string;
}

export async function queryData(options: QueryOptions) {
    // 实现复杂查询逻辑
}

Deployment and Testing

Local Development

1. Modify the tool code.
2. Run npm run build to compile.
3. Start the server, and it will automatically load the updated tools.

Testing

• Ensure that all API calls are successful and return the correct data.
• Verify that the query function works as expected.

📄 License

No license information provided in the original document.

🔧 Technical Details

The purpose of this project is to enable interaction with personal YNAB budgets through AI conversations. The main workflow is as follows:

• First-time Setup: Prompt to select the budget, and provide the necessary environment variables.
• Core Functions: Import budget data, support complex queries, and provide real-time feedback.

📚 Learning Resources

• MCP Framework GitHub
• MCP Framework Documentation

⚠️ Important Note

This token is never sent directly to the LLM. It is privately stored as an environment variable and is only used to call the YNAB API.

💡 Usage Tip

When adding this MCP server to any client, you need to provide your personal access token as YNAB_API_TOKEN.