Wallos MCP Server

An MCP (Model Context Protocol) server that enables Claude Desktop to interact with your Wallos subscription management instance.

Overview

This MCP server provides tools for managing subscriptions, categories, currencies, payment methods, and household members in Wallos through Claude Desktop. It acts as a bridge between Claude and your self-hosted Wallos instance.

Features

• 📊 View and manage subscriptions
• 📁 Organize with categories
• 💱 Handle multiple currencies
• 💳 Manage payment methods
• 👥 Configure household members
• 📈 Access statistics and insights
• 🔔 Check upcoming payments

Prerequisites

• Wallos instance (self-hosted or Docker)
• Bun runtime ()
• Claude Desktop
• Wallos user credentials

Installation

1. Clone this repository:

git clone https://github.com/yourusername/wallos-mcp.git
cd wallos-mcp

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env
# Edit .env with your Wallos instance details

1. Build the project:

bun run build

1. Add to Claude Desktop config:

{
  "mcpServers": {
    "wallos": {
      "command": "bun",
      "args": ["/path/to/wallos-mcp/dist/index.js"],
      "env": {
        "WALLOS_URL": "http://localhost:8282",
        "WALLOS_USERNAME": "your_username",
        "WALLOS_PASSWORD": "your_password"
      }
    }
  }
}

Available Tools

create_subscription

Create a new subscription with automatic entity creation. This powerful tool handles all the complexity of creating related entities automatically.

Features:

• 🌍 Currency by Code: Specify currencies using codes (USD, EUR, GBP, etc.) - automatically creates if doesn’t exist
• 📅 Flexible Frequency: Natural language billing periods (‘daily’, ‘weekly’, ‘monthly’, ‘quarterly’, ‘bi-weekly’, ‘3 months’)
• 🏷️ Smart Entity Creation: Automatically creates missing categories, payment methods, and household members
• 👥 Payer Management: Specify payer by name with optional email - creates household member if needed
• 📆 Intelligent Date Handling: Smart calculation of next payment date, always ensuring it’s in the future

Parameters:

• name (required): Subscription service name
• price (required): Subscription price amount
• currency_code: Currency code (e.g., USD, EUR) - creates if needed
• currency_id: Use existing currency ID (alternative to currency_code)
• billing_period: Flexible period (‘monthly’, ‘quarterly’, ‘2 weeks’, etc.)
• billing_frequency: Multiplier for billing period (default: 1)
• category_name: Category name (creates if needed, prioritized over category_id)
• category_id: Use existing category ID
• payment_method_name: Payment method name (creates if needed)
• payment_method_id: Use existing payment method ID
• payer_user_name: Household member name (creates if needed)