Expense Log MCP

A MCP server that provides tools for logging expenses.

✨ Features

• Log a new expense to a ledger.
• Delete an expense record.
• Retrieve a list of all available expense categories.
• Retrieve and group expenses by payer and category.

🚀 Getting Started

Prerequisites

• Node.js
• A PostgreSQL database

Installation & Setup

1. Clone the repository:

   git clone https://github.com/evanxd/expense-log-mcp.git

2. Install dependencies:

   npm install

3. Set up the database:

   • Create a .env file in the root of the project.
   • Add your PostgreSQL connection string to the .env file:

     DB_USER="postgres"
     DB_HOST="localhost"
     DB_PORT="5432"
     DB_DATABASE="postgres"
     DB_PASSWORD="YOUR_DB_PASSWORD"
     DATABASE_URL="postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_DATABASE}?schema=public"

   • Apply the database schema:

     npx prisma db push

   • Seed the database with initial categories:

     npm run db:seed

4. Build the project:

   npm run build

5. Set up the MCP server:

   • Add the following configuration to your MCP host (e.g., Gemini CLI) settings:

   "mcpServers": {
     "expense-log-mcp": {
       "command": "node",
       "args": [
         "/path/to/expense-log-mcp/dist/index.js"
       ],
       "env": {
         "DATABASE_URL": "postgresql://postgres:YOUR_DB_PASSWORD@localhost:5432/postgres?schema=public"
       }
     }
   }

🛠️ Tools

The server exposes the following tools:

addExpense

Adds a new expense record.

Parameters:

| Name | Type | Description | |---------------|--------|----------------------------------------------------| | ledgerId | string | The ID of the ledger to add the expense to. | | categoryId | string | The ID of the expense category. | | messageId | string | A unique ID for the message to prevent duplicates. | | description | string | A description of the expense. | | amount | number | The amount of the expense. | | payer | string | The name of the person who paid. |

Returns:

A JSON string confirming the expense has been added, e.g.:

{
  "success": true,
  "code": "OK",
  "message": "Expense added successfully.",
  "data": {
    "expenseId": "clx...456"
  }
}

deleteExpense

Deletes an expense record.

Parameters:

| Name | Type | Description | |-------------|--------|-----------------------------------------------------| | ledgerId | string | The ID of the ledger the expense belongs to. | | messageId | string | The unique message ID of the expense to be deleted. |

Returns:

A JSON string confirming the expense has been deleted, and including details of the deleted expense, e.g.:

{
  "success": true,
  "code": "OK",
  "message": "Expense deleted successfully.",
  "data": {
    "id": "clx...123",
    "description": "Lunch",
    "amount": 15.75,
    "createdAt": "Sun Sep 07 2025"
  }
}

getExpenseCategories

Retrieves the list of all expense categories.

Parameters:

None.

Returns:

A JSON string containing the list of expense categories, e.g.:

{
  "success": true,
  "code": "OK",
  "message": "Expense categories retrieved successfully.",
  "data": [
    {
      "expenseCategoryId": "clx...1",
      "expenseCategoryName": "Transportation"
    },
    {
      "expenseCategoryId": "clx...2",
      "expenseCategoryName": "Utilities"
    }
  ]
}

getGroupedExpenses

Retrieves and groups expenses by payer and then by category name, returning the total amount for each category, with optional filters for category IDs, payer, and a date range.

Parameters:

| Name | Type | Description | |---------------|----------|--------------------------------------------------------------------| | ledgerId | string | The ID of the ledger to retrieve expenses from. | | categoryIds | string[] | Optional. An array of category IDs to filter by. | | payer | string | Optional. The name of the payer to filter by. | | startDate | string | Optional. The start date for filtering expenses (ISO 8601 format). | | endDate | string | Optional. The end date for filtering expenses (ISO 8601 format). |

Returns:

A JSON string containing the grouped expenses, e.g.:

{
  "success": true,
  "code": "OK",
  "message": "Grouped expenses retrieved successfully.",
  "data": {
    "Payer1": {
      "expenseCategories": {
        "Entertainment": 100,
        "Transportation": 50
      },
      "totalAmount": 150
    },
    "Payer2": {
      "expenseCategories": {
        "Dining/Snacks": 75
      },
      "totalAmount": 75
    }
  }
}

🗄️ Database Schema

This project uses Prisma to manage the database schema. The schema is defined in prisma/schema.prisma and includes the following models:

• Ledger: Represents a collection of expenses.
• ExpenseCategory: Represents a category for an expense.
• Expense: Represents a single expense record. A unique constraint is added on ledgerId and messageId to prevent duplicate expenses.

All models include createdAt and updatedAt timestamps. IDs are generated using cuid().

🙌 Contributing

Contributions are welcome! Please feel free to submit a pull request.

📄 License

This project is licensed under the MIT License.