@berlm/expenseowl-authelia-mcp-server

MCP (Model Context Protocol) server for ExpenseOwl API integration.

Overview

This package provides a Model Context Protocol server that exposes ExpenseOwl's REST API as MCP tools. It includes 16 tools for managing expenses, recurring expenses, categories, and configuration.

Installation

npm install @berlm/expenseowl-authelia-mcp-server

Environment Variables

Before running the server, you must configure these environment variables:

• EXPENSEOWL_API_URL - Base URL for your ExpenseOwl API (e.g., http://localhost:8080)
• EXPENSEOWL_USERNAME - Username for HTTP Basic Authentication
• EXPENSEOWL_PASSWORD - Password for HTTP Basic Authentication

Example .env file:

EXPENSEOWL_API_URL=http://localhost:8080
EXPENSEOWL_USERNAME=admin
EXPENSEOWL_PASSWORD=secret

Development

Setup

npm install

Build

npm run build

Watch Mode

npm run watch

Usage

The MCP server runs on stdio and can be integrated with MCP-compatible applications.

MCP Configuration

Add to your MCP settings (e.g., in Claude Desktop or other MCP clients):

{
  "mcpServers": {
    "expenseowl": {
      "command": "node",
      "args": ["/path/to/@berlm/expenseowl-authelia-mcp-server/dist/index.js"],
      "env": {
        "EXPENSEOWL_API_URL": "http://localhost:8080",
        "EXPENSEOWL_USERNAME": "admin",
        "EXPENSEOWL_PASSWORD": "secret"
      }
    }
  }
}

Available Tools

Configuration Tools (7)

1. get_config - Get the full ExpenseOwl configuration

   • Returns: categories, base currency, billing cycle start day, and recurring expenses

2. get_categories - Get the list of all expense categories

   • Returns: Array of category names

3. update_categories - Replace the entire list of expense categories

   • Input: { categories: string[] }
   • Note: Each category is sanitized server-side

4. get_currency - Get the base currency code

   • Returns: Currency code (e.g., "usd", "eur", "gbp")

5. update_currency - Set the base currency code

   • Input: { currency: string }
   • Supported currencies: usd, eur, gbp, jpy, cny, krw, inr, rub, brl, zar, aed, aud, cad, chf, hkd, bdt, sgd, thb, try, mxn, php, pln, sek, nzd, dkk, idr, ils, vnd, myr, mad

6. get_start_date - Get the billing cycle start day

   • Returns: Integer (1-31)

7. update_start_date - Set the billing cycle start day

   • Input: { startDate: number } (must be 1-31)

Expense Tools (5)

8. create_expense - Create a new expense

   • Input:

     {
       "name": "Lunch",
       "category": "Food",
       "amount": 12.5,
       "currency": "usd",
       "date": "2025-10-22T12:30:00Z",
       "tags": ["office", "takeout"]
     }

   • Validation: name and category required, amount cannot be zero, date required in RFC3339 format

9. get_expenses - Get all expenses

   • Returns: Array of expense objects

10. update_expense - Update an existing expense

    • Input: { id: string, expense: Expense }

11. delete_expense - Delete a single expense

    • Input: { id: string }

12. delete_expenses_batch - Delete multiple expenses

    • Input: { ids: string[] }

Recurring Expense Tools (4)

13. create_recurring_expense - Create a recurring expense

    • Input:

      {
        "name": "Gym Membership",
        "amount": 30.0,
        "currency": "usd",
        "category": "Healthcare",
        "tags": ["fitness"],
        "startDate": "2025-11-01T00:00:00Z",
        "interval": "monthly",
        "occurrences": 12
      }

    • Validation: occurrences must be ≥ 2, interval must be one of: daily, weekly, monthly, yearly

14. get_recurring_expenses - Get all recurring expenses

    • Returns: Array of recurring expense objects

15. update_recurring_expense - Update a recurring expense

    • Input: { id: string, updateAll: boolean, recurringExpense: RecurringExpense }
    • updateAll: if true, also updates all expenses generated from this recurring expense

16. delete_recurring_expense - Delete a recurring expense

    • Input: { id: string, removeAll: boolean }
    • removeAll: if true, also deletes all expenses generated from this recurring expense

Data Models

Expense

{
  id?: string;
  recurringID?: string;
  name: string;
  tags?: string[];
  category: string;
  amount: number;  // Cannot be zero
  currency: string;
  date: string;    // RFC3339 format
}

RecurringExpense

{
  id?: string;
  name: string;
  amount: number;
  currency: string;
  tags?: string[];
  category: string;
  startDate: string;  // RFC3339 format
  interval: "daily" | "weekly" | "monthly" | "yearly";
  occurrences: number;  // Minimum 2
}

Config

{
  categories: string[];
  currency: string;
  startDate: number;  // 1-31
  recurringExpenses: RecurringExpense[];
}

Validation Rules

All validation is performed both client-side (via Zod schemas) and server-side:

• Names and Categories: Must be non-empty after sanitization. Sanitization strips disallowed characters and collapses whitespace. Allowed chars: letters, numbers, spaces, and .,-'_!".
• Amounts: Must be non-zero.
• Dates: Must be provided in RFC3339 format (e.g., 2025-10-22T12:34:56Z).
• Tags: Empty tags are dropped after sanitization.
• Recurring Occurrences: Must be at least 2.
• Intervals: Must be one of: daily, weekly, monthly, yearly.

Error Handling

All errors from the ExpenseOwl API are passed through directly to the MCP client. Common errors:

• 400 Bad Request: Validation failed or invalid request body
• 405 Method Not Allowed: Wrong HTTP method
• 500 Internal Server Error: Backend/storage failure

Error responses follow this format:

{
  "error": "human readable message"
}

Publishing

npm publish

Note: Make sure you're logged in to npm (npm login) and have the necessary permissions to publish scoped packages.

License

MIT