# Budget Surplus Calculator AI Agent Connect

> Budget Surplus Calculator MCP gives your AI client direct access to your budget data. It lets you check net positions, compare income against expenses, and see exactly how much you are spending in specific categories across different timeframes.

## Overview
- **Category:** productivity
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_s2ZATZdZ4pZzik9O6uGWjsQKilfGuVRTa1oDsDe1/ai-agent-connect
- **Tags:** budget, surplus, deficit, income, expenses

## Description

You can stop digging through spreadsheets to find out where your money went. This MCP connects your AI client to your budget data so you can ask direct questions about your finances. Instead of manually calculating totals, you just ask your agent to find your surplus or deficit for a specific period. You can pull high-level breakdowns to see the gap between what you earn and what you spend, or drill down into specific categories to see where the leaks are. It works by pulling data from your defined budget periods and running the math for you instantly. Whether you need to know your net position for last quarter or just want a summary of your grocery spending, your AI client handles the heavy lifting.

## Tools

### get_category_summary
This tool provides a breakdown of spending within specific budget categories. It shows you exactly how funds are distributed across your chosen labels.

### get_income_vs_expense_breakdown
This tool compares your total income against your total expenses. It gives you a high-level view of your cash flow for a given period.

### get_net_position
This tool calculates whether a specific budget period resulted in a surplus or a deficit. It returns the final net financial standing for that timeframe.

### list_budget_periods
This tool retrieves all available timeframes in your budget. Use it to find the correct period ID before asking for specific financial data.

## Prompt Examples

**Prompt:** 
```
What is my net position for period P-2024-Q1?
```

**Response:** 
```
Your net position for period P-2024-Q1 is a SURPLUS of $1,250.00.
```

**Prompt:** 
```
Show me the breakdown of income and expenses for period P-2024-Q1.
```

**Response:** 
```
For period P-2024-Q1, your total income was $5,000.00 and your total expenses were $3,750.00, resulting in a difference of $1,250.00.
```

**Prompt:** 
```
How much did I spend on groceries in period P-2024-Q1?
```

**Response:** 
```
In period P-2024-Q1, your total spending for the Groceries category was $450.00.
```

## Capabilities

### Net Position Tracking
Your agent calculates if you are in a surplus or deficit for any period.

### Cash Flow Comparison
The AI compares total income against total expenses to show your margin.

### Category Analysis
Your client summarizes spending totals for specific budget categories.

### Period Discovery
The AI identifies available budget timeframes to ensure accurate queries.

## Use Cases

### Monthly Review
Ask your agent for a breakdown of income versus expenses at the end of every month.

### Spending Audits
Use category summaries to see if your grocery or utility spending is increasing.

### Quarterly Reporting
Get the net position for specific quarterly periods to track long term trends.

### Budget Planning
Check your current surplus to determine how much you can allocate to new categories.

## Benefits

- Eliminates manual math by letting the AI calculate net positions.
- Provides instant category summaries without spreadsheet filtering.
- Identifies surplus or deficit states through direct natural language questions.
- Connects your existing budget data to any MCP-compatible client.

## How It Works

The process moves from connecting your client to getting specific financial answers.

1. Connect your preferred AI client to the Vinkius hosted MCP.
2. Ask your agent to list available budget periods to find the right timeframe.
3. Request a specific calculation like a net position or category summary.
4. The AI executes the tool and presents the calculated data in plain text.

## Frequently Asked Questions

**How do I connect this MCP to my AI client?**
You connect once through the Vinkius interface. After that, the MCP is ready to use in Claude, Cursor, Windsurf, or any other compatible client.

**Can I use this with Claude?**
Yes. This MCP is designed to work with any MCP-compatible client, including Claude.

**Do I need to host the MCP myself?**
No. Vinkius hosts and manages the MCP for you, so it is ready to run immediately upon connection.

**What kind of budget data can I analyze?**
You can analyze income, expenses, category distributions, and net surpluses or deficits across different budget periods.

**Do I need to provide my own API keys?**
Vinkius manages the credentials and hosting, so you don't have to worry about the backend setup.

**How do I see my current financial status?**
You can use the `get_net_position` tool to find out if you have a surplus or a deficit for a specific budget period.

**Can I see a breakdown of my spending?**
Yes, use `get_category_summary` to see how much is attributed to specific categories like rent or groceries.

**What budget periods are available?**
You can call `list_budget_periods` to retrieve all recorded timeframes.