Budgetsco MCP Server
# Budgetsco MCP Server
MCP Server for Budgetsco, enabling personal finance management through transactions, budgeting, and financial tracking capabilities.
## Table of Contents
- [Prerequisites](#prerequisites)
- [Setup](#setup)
- [Available Tools](#available-tools)
- [Development](#development)
- [Configuration](#configuration)
- [License](#license)
## Prerequisites
- Node.js (version 22.x recommended)
- Check your Node.js version with: `node --version`
- A Budgetsco personal access token
## Setup
1. Clone the repository
2. Create a `.env` file in the root directory with your Budgetsco access token:
```env
BUDGETSCO_ACCESS_TOKEN='your_access_token_here'
```
3. Install dependencies:
```bash
npm install
```
## Available Tools
The server provides several tools for managing personal finances:
### Transactions
- Create, edit, and delete transactions
- View transaction history with flexible filters
- Support for various payment modes (Cash, Credit Card, UPI, etc.)
### Categories
- Get predefined and custom categories
- Create and manage custom categories
- Categorize transactions for better financial tracking
### Recurring Transactions
- Set up automated recurring transactions
- Manage daily, monthly, or yearly recurring entries
- Skip or mark recurring transactions as complete
### Budgeting
- Set and manage budgets for different categories
- Track budget utilization
- Get detailed budget breakdowns
### Currency
- Set and manage currency preferences
- Support for multiple international currencies
## Development
Available commands:
- `npm run dev`: Launch [MCP Inspector](https://github.com/modelcontextprotocol/inspector) against the server (`tsx src/server.ts`)
- `npm run start`: Run the production server
- `npm run build`: Build the project
- `npm run lint`: Run linting checks
- `npm run format`: Format code
- `npm run test`: Run tests
## Configuration
### Environment Variables
- `BUDGETSCO_ACCESS_TOKEN` (required): Your Budgetsco personal access token
### Client Configuration
To use this MCP server with clients like Claude, add the following configuration:
```json
{
"mcpServers": {
"budgetsco": {
"command": "npx",
"args": ["@budgetsco/mcp"],
"env": {
"BUDGETSCO_ACCESS_TOKEN": "<YOUR_TOKEN>"
}
}
}
}
```
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
---
Built with the official [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) (`@modelcontextprotocol/sdk`). The server uses stdio transport; log diagnostics to stderr only so stdout stays reserved for JSON-RPC.
TDQS
Scored across 18 tools
Each tool targets a distinct resource-action combination: transactions, recurring transactions, budget, currency, and categories have separate create/read/update/delete operations. The only potential overlap between getCategoriesByType and getCustomCategories is resolved by their specific scopes (general vs. user-created). No two tools appear to serve the same purpose.
All tools follow a consistent verb_noun pattern (create, delete, get, edit, mark, skip, set) with clear resource nouns. However, there is minor inconsistency in plural/singular usage: getters like getTransactions and getRecurringTransactions use plural, while createTransaction and createRecurringTransaction use singular, and getCustomCategories uses plural while createCustomCategories also uses plural. This is a small deviation from a fully uniform convention.
With 18 tools, the server is slightly above the typical 3-15 range, but the breadth of domain resources (transactions, recurring transactions, categories, budget, currency) justifies the count. Each tool has a clear purpose, and no redundant tools are present, so the count feels reasonable for a budgeting application.
The tool surface covers full CRUD for transactions and recurring transactions, plus essential get/set operations for budget and currency. Categories support creation, deletion, and retrieval, but there is no edit operation for custom categories, which is a minor gap. Overall, the core workflows are covered with only a few missing lifecycle operations.