CashBook MCP Server

A Model Context Protocol (MCP) server for the CashBook application. This allows VS Code's AI Assistant (GitHub Copilot) to interact with your CashBook API to create transactions, view categories, and manage your cash book entries.

What is MCP?

Model Context Protocol is a standard that allows AI assistants to interact with tools and services. By creating an MCP server, we expose CashBook's APIs as tools that Copilot can use directly in VS Code chat.

Architecture

VS Code Chat (Copilot)
    ↓ calls MCP tools
MCP Server (this repo)
    ↓ HTTP requests
NestJS Backend (apps/api)
    ↓
MongoDB

Setup

1. Install Dependencies

cd mcp
npm install
# or
pnpm install

2. Configure Environment Variables

Copy .env.example to .env:

cp .env.example .env

Edit .env:

CASHBOOK_API_URL=http://localhost:3000
CASHBOOK_AUTH_TOKEN=your_jwt_token_here
CASHBOOK_BUSINESS_ID=

How to get CASHBOOK_AUTH_TOKEN:

1. Start your CashBook application (pnpm dev in the root)
2. Open http://localhost:3173 (web app)
3. Login with your credentials
4. Open Browser DevTools → Application → Cookies
5. Copy the value of your auth token (usually stored in localStorage under auth_token or similar)
6. Paste it into .env

3. Build the MCP Server

npm run build
# or
pnpm run build

4. Register with VS Code

Add the following to your VS Code settings.json or .copilot-instructions.md:

Via VS Code Settings (settings.json):

{
  "modelContextProtocol": {
    "servers": {
      "cashbook-mcp": {
        "command": "node",
        "args": [
          "C:\\Users\\suraj\\CashBookWorkSpace\\cash-book-app\\mcp\\dist\\index.js"
        ],
        "env": {
          "CASHBOOK_API_URL": "http://localhost:3000",
          "CASHBOOK_AUTH_TOKEN": "your_jwt_token",
          "CASHBOOK_BUSINESS_ID": ""
        }
      }
    }
  }
}

Or via Copilot Instructions (create .copilot-instructions.md in root):

# CashBook MCP Server

Use the following MCP server for CashBook operations:

- Server: cashbook-mcp
- Location: ./mcp/dist/index.js
- Node: Required

Available tools:
- send_bot_message: Create transactions from natural language
- list_categories: View all transaction categories
- get_recent_transactions: View recent entries
- get_business_info: View business details

Usage Examples

Once registered, you can use it in Copilot chat:

Example 1: Create a Transaction

@cashbook-mcp I need to record that I paid 250 rupees for transport by auto

MCP will call send_bot_message("paid 250 for transport auto") → Creates transaction

Example 2: View Categories

@cashbook-mcp What categories do I have available?

MCP will call list_categories() → Lists all income/expense categories

Example 3: View Recent Entries

@cashbook-mcp Show me my last 10 transactions

MCP will call get_recent_transactions(10) → Lists transactions

Example 4: Create Multiple Entries

@cashbook-mcp Create these transactions for me:
- Cash in 1200 from sales
- Cash out 150 for groceries
- Cash out 500 for rent

MCP will create all three transactions

Available Tools

1. send_bot_message

• Description: Send natural language to create transactions
• Input: message (string) - e.g., "cash out 250 transport"
• Example: User says "I spent 150 on groceries" → MCP creates expense entry
• Uses: WhatsappAiService (GPT-4o or heuristic parser)

2. list_categories

• Description: Get all available transaction categories
• Input: None
• Returns: List of income and expense categories

3. get_recent_transactions

• Description: Fetch recent transactions
• Input: limit (optional, default 20)
• Returns: List of transactions with amounts, dates, categories

4. get_business_info

• Description: Get current business details
• Input: None
• Returns: Business name, currency, ID

Development

Run in Watch Mode

npm run dev

Build

npm run build

Debug

Check logs in VS Code output:

Output → MCP or similar

Troubleshooting

Issue: "CASHBOOK_AUTH_TOKEN is not set"

Solution: Make sure .env file has the auth token. Restart VS Code after updating.

Issue: "Connection refused" on localhost:3000

Solution: Make sure your NestJS backend is running:

cd apps/api
pnpm dev

Issue: MCP tool not showing in Copilot

Solution:

1. Check that settings.json has correct server configuration
2. Verify the file path to dist/index.js exists
3. Run npm run build to generate dist folder
4. Restart VS Code

Issue: "Failed to send bot message"

Solution:

1. Check that auth token is valid (login again if needed)
2. Verify backend is running and accessible
3. Check .env has correct CASHBOOK_API_URL

Project Structure

mcp/
├── src/
│   ├── index.ts           # Main MCP server
│   └── cashbook-client.ts # HTTP client wrapper
├── dist/                  # Compiled output
├── package.json
├── tsconfig.json
├── .env                   # Your environment variables
├── .env.example           # Template
└── README.md

How It Works

1. VS Code opens chat and user mentions @cashbook-mcp
2. Copilot calls the MCP server's tools/list endpoint
3. MCP Server returns list of available tools (send_bot_message, list_categories, etc.)
4. User invokes a tool (e.g., "Create a transaction for 250 rupees")
5. MCP Server receives the request, validates it, calls the appropriate method
6. Cashbook Client makes HTTP request to NestJS backend
7. NestJS Backend processes request (calls WhatsappAiService, creates transaction in MongoDB)
8. Response flows back: MongoDB → Backend → Client → MCP → Copilot Chat
9. User sees formatted result with transaction details

Security Notes

⚠️ Important:

• Never commit .env to version control (already in .gitignore)
• Auth tokens are sensitive - store securely
• For production, consider using OAuth or service accounts
• MCP server runs locally - data doesn't leave your machine

Next Steps

1. ✅ Install dependencies: npm install
2. ✅ Create .env file with auth token
3. ✅ Build: npm run build
4. ✅ Update VS Code settings with MCP server config
5. ✅ Restart VS Code
6. ✅ Try it in Copilot chat!

Support

For issues or questions:

1. Check the troubleshooting section above
2. Verify backend is running and accessible
3. Check console output in VS Code for error messages
4. Verify .env has correct token and URL