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 (https://bun.sh)
• 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)
• payer_user_email: Email for new household member
• payer_user_id: Use existing household member ID
• start_date: Subscription start date (YYYY-MM-DD)
• next_payment: Next payment date (auto-calculated if not provided)
• auto_renew: Whether subscription auto-renews (default: true)
• notes: Additional notes (supports multiline)
• url: Service URL
• notify: Enable renewal notifications
• notify_days_before: Days before renewal to notify

Example Usage:

{
  "name": "Netflix Premium",
  "price": 15.99,
  "currency_code": "USD",
  "billing_period": "monthly",
  "category_name": "Entertainment",
  "payment_method_name": "Credit Card",
  "payer_user_name": "John Smith",
  "payer_user_email": "[email protected]",
  "start_date": "2024-01-15",
  "auto_renew": true,
  "notify": true,
  "notify_days_before": 3,
  "notes": "Premium family plan\n4K streaming\n4 simultaneous screens",
  "url": "https://netflix.com"
}

list_subscriptions

View all subscriptions with comprehensive filtering options.

Parameters:

• member_ids: Comma-separated member IDs (e.g., "1,3,5")
• category_ids: Comma-separated category IDs
• payment_method_ids: Comma-separated payment method IDs
• state: Filter by state ('active' or 'inactive')
• sort: Sort field (name, id, next_payment, price, etc.)
• disabled_to_bottom: Sort inactive subscriptions to bottom
• convert_currency: Convert prices to main currency

get_master_data

Retrieve all master data (categories, currencies, payment methods, household members) in a single call.

Category Management Tools

• add_category: Create a new category
• update_category: Update category name
• delete_category: Remove a category (unless it's the default)

Implementation Plan

Phase 1: Core Infrastructure ✅

• [x] Repository setup
• [x] TypeScript configuration
• [x] MCP SDK integration setup
• [x] Complete CI/CD pipeline with GitHub Actions
• [x] Docker build and security scanning
• [x] Comprehensive development tooling (justfile)
• [x] Code quality tools (Super Linter, ESLint, Prettier)
• [ ] Wallos API client with session management
• [ ] Error handling and logging

Phase 2: Subscription Management

• [x] list_subscriptions - View all subscriptions with filters
• [x] create_subscription - Create new subscription with automatic entity creation
• [ ] edit_subscription - Modify existing subscription
• [ ] delete_subscription - Remove subscription
• [ ] get_subscription - Detailed subscription info
• [ ] clone_subscription - Duplicate subscription
• [ ] toggle_subscription - Enable/disable subscription

Phase 3: Master Data Tools

• [ ] manage_categories - CRUD operations for categories
• [ ] manage_payment_methods - Add/edit/remove payment methods
• [ ] manage_currencies - Currency management with exchange rates
• [ ] manage_household - Household member operations

Phase 4: Analytics & Insights

• [ ] get_statistics - Spending statistics and trends
• [ ] upcoming_payments - Next payment schedule
• [ ] spending_by_category - Category breakdown
• [ ] get_budget_status - Budget vs actual spending
• [ ] export_data - Export subscriptions to CSV/JSON

Phase 5: Advanced Features

• [ ] search_logos - Find logos for subscriptions
• [ ] bulk_operations - Mass update subscriptions
• [ ] notifications_status - Check notification settings
• [ ] calculate_savings - Identify savings opportunities
• [ ] sync_exchange_rates - Update currency rates

Architecture

Tech Stack

• Language: TypeScript
• Runtime: Node.js
• MCP SDK: @modelcontextprotocol/sdk
• HTTP Client: axios
• Session Management: tough-cookie
• Environment: dotenv

Project Structure

wallos-mcp/
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── wallos-client.ts         # Wallos API wrapper
│   ├── tools/                   # MCP tool implementations
│   │   ├── subscriptions.ts     # Subscription management tools
│   │   ├── categories.ts        # Category tools
│   │   ├── currencies.ts        # Currency tools
│   │   ├── payments.ts          # Payment method tools
│   │   ├── household.ts         # Household tools
│   │   └── analytics.ts         # Statistics and insights
│   ├── types/                   # TypeScript type definitions
│   │   ├── index.ts             # Main types export
│   │   ├── wallos.ts            # Wallos API types
│   │   └── mcp.ts               # MCP-specific types
│   └── utils/                   # Utility functions
│       ├── session.ts           # Session management
│       ├── logger.ts            # Logging utilities
│       └── validators.ts        # Input validation
├── tests/                       # Test files
├── dist/                        # Compiled JavaScript
├── .env.example                 # Environment template
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

API Communication Flow

1. Authentication:

   • MCP server starts → Creates session with Wallos
   • Stores session cookie for subsequent requests
   • Handles session expiry and renewal

2. Request Flow:

   Claude Desktop → MCP Tool → Wallos Client → Wallos API → SQLite DB
                          ↓                           ↓
                    Response ← JSON Response ← PHP Endpoint

3. Session Management:

   • Persistent session across tool calls
   • Automatic re-authentication on expiry
   • Secure credential storage in environment

Security Considerations

• Credentials stored in environment variables
• Session-based authentication with Wallos
• Input validation on all tool parameters
• No direct database access (API-only)
• Respects Wallos user permissions

CI/CD Pipeline

GitHub Actions Workflows

• Code Quality & Linting: TypeScript checking, ESLint, Prettier formatting, security audits
• Test & Build: Unit testing and build verification with Node.js compatibility (18, 20, 22)
• Docker Build: Multi-platform builds with security scanning
• Super Linter: Comprehensive code quality checks with 10+ linters
• Automatic Publishing: Docker images to GitHub Container Registry

Quality Assurance

# Local development workflow
just lint     # ESLint + TypeScript + Markdown linting
just fmt      # Prettier + markdownlint formatting
just superlint # Comprehensive Super Linter (fast)
just superlint-verbose # Detailed debugging output

All workflows run automatically on pushes and pull requests with smart validation modes.

Development

Quick Start with Just

# Initial setup (installs deps, creates .env)
just setup

# Start development server
just start

# Run all quality checks
just check

# Build and test
just build && just test

Manual Setup

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Build for production
bun run build

Testing Tools Locally

# Start local MCP server
bun run start:local

# Test with MCP client
bunx @modelcontextprotocol/cli test

Tool Reference

For detailed information about available tools, see the Available Tools section above.

Currently Implemented Tools

Subscription Management

• create_subscription - Create new subscription with auto entity creation
• list_subscriptions - List subscriptions with filters

Master Data

• get_master_data - Get all categories, currencies, payment methods, household

Category Management

• add_category - Add new category
• update_category - Update category name
• delete_category - Delete category (except default)

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Roadmap

• [ ] Batch operations support
• [ ] Caching layer for frequently accessed data
• [ ] WebSocket support for real-time updates
• [ ] Multi-user household support
• [ ] Backup and restore tools
• [ ] Integration with calendar services
• [ ] Natural language subscription entry

License

MIT License - See LICENSE file for details

Support

• Wallos Documentation
• MCP Documentation
• Issues

Acknowledgments

• Wallos by Ellite
• Model Context Protocol by Anthropic