Home Automation MCP Server

MCP server for home automation businesses - manage clients and projects using natural language through Claude Desktop.

Features

• 🤖 Natural Language Interface - Talk to Claude to manage your business data
• 👥 Client Management - Create and search clients with automatic account number generation
• 📊 Project Management - Track projects with unique project codes and client linking
• 🔐 Secure - Employee authentication with Supabase, RLS-enforced data isolation
• 🏢 Multi-tenant - Organization-based data separation
• 🔄 Preview Mode - Review data before committing to database
• 🍎 macOS Keychain - Secure credential storage (no plaintext secrets)

Quick Start

Installation

npm install -g home-automation-mcp

Setup

Run the setup wizard to configure your Supabase connection and employee credentials:

cd $(npm root -g)/home-automation-mcp
./scripts/setup-employee-auth.sh

You'll be prompted for:

• Supabase URL (e.g., https://your-project.supabase.co)
• Supabase Anon Key (from Supabase Dashboard → Settings → API)
• Your Email (employee account email)
• Your Password (employee account password)

All credentials are securely stored in macOS Keychain.

Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "home-automation": {
      "command": "home-automation-mcp"
    }
  }
}

Restart Claude Desktop and you're ready!

Usage Examples

Create a Client

You: Create a new client named John Smith with preview first

Claude: [Shows preview of all data and database actions]

You: Yes, that looks good, create it

Claude: ✅ Client created successfully with account number MOD-SMI25-12345678

Search Clients

You: Find all clients who signed up in 2025

Claude: Found 12 clients:
- John Smith (MOD-SMI25-12345678)
- Jane Doe (MOD-DOE25-87654321)
...

Create a Project

You: Create a project for John Smith
  Title: "Main Street Security System"
  Address: "123 Main Street, London"

Claude: ✅ Project created with code SMIT001-MAIN-25

Available Tools

Client Management

• create_client - Create new client with contact and address information

  • Supports preview mode (preview: true)
  • Auto-generates UK-format account numbers (MOD-XXX25-12345678)
  • Stores address in dedicated table (not as unstructured notes)

• find_client - Search clients by name, account number, or year

  • Full-text search on names
  • Filter by signup year
  • Limit results (default 10)

Project Management

• create_project - Create new project for a client

  • Supports preview mode (preview: true)
  • Auto-generates project codes (SMIT001-MAIN-25)
  • Links to client and address

• generate_account_number - Generate client account numbers

• generate_project_id - Generate project codes

• validate_account_number - Validate account number format

Database Schema

The server expects a Supabase database with the following tables:

Core Tables

• contacts - Client/contact records
• addresses - Physical addresses (deduplicated)
• projects - Project records
• contact_addresses - Junction table linking contacts to addresses
• contact_types - Contact type lookup (client, supplier, contractor, etc.)
• project_statuses - Project status lookup (quote, approved, in_progress, completed)

Authentication & Security

• users - Employee accounts with is_active flag
• organisations - Multi-tenant organization records
• activity_log - Audit trail of all changes

All tables use Row Level Security (RLS) to enforce organization-based data isolation.

Security Model

Authentication Flow

1. Employee authenticates with email/password
2. Supabase issues JWT token
3. Token stored in macOS Keychain
4. All API calls include JWT
5. RLS policies enforce organisation_id filtering

No Secrets in Code

• ✅ Supabase URL - Configured during setup
• ✅ Supabase Anon Key - Configured during setup (public key, safe to expose)
• ✅ Employee credentials - Never stored in code, only in Keychain
• ✅ JWT tokens - Stored in Keychain, auto-refreshed

Data Isolation

-- Example RLS Policy
CREATE POLICY "Users see only their org's contacts"
  ON contacts
  FOR ALL
  USING (organisation_id = auth.jwt() -> 'organisation_id');

Even if someone installs this package, they cannot access your data without:

1. Your Supabase URL
2. Valid employee credentials in your database
3. Active status (is_active = true)

Platform Support

• macOS (required for Keychain storage)
• Node.js 18.0.0 or higher

Linux/Windows support coming soon (will use environment variables instead of Keychain).

Updating

npm update -g home-automation-mcp

Credentials are preserved in Keychain - no need to re-authenticate.

Development

Clone and Build

git clone https://github.com/modalav/home-automation-mcp.git
cd home-automation-mcp
npm install
npm run build

Run Locally

npm run dev

Run Tests

npm test

Architecture

┌─────────────────────────────────────────┐
│         Claude Desktop (User)           │
└───────────────┬─────────────────────────┘
                │ MCP Protocol (stdio)
┌───────────────▼─────────────────────────┐
│     home-automation-mcp (This Package)  │
│  ┌─────────────────────────────────┐    │
│  │  Tool Handlers                  │    │
│  │  - create_client                │    │
│  │  - find_client                  │    │
│  │  - create_project               │    │
│  └──────────────┬──────────────────┘    │
│                 │                        │
│  ┌──────────────▼──────────────────┐    │
│  │  SupabaseService                │    │
│  │  - Authentication (JWT)         │    │
│  │  - CRUD operations              │    │
│  │  - RLS enforcement              │    │
│  └──────────────┬──────────────────┘    │
│                 │                        │
│  ┌──────────────▼──────────────────┐    │
│  │  KeychainService                │    │
│  │  - Load credentials             │    │
│  │  - Token refresh                │    │
│  └─────────────────────────────────┘    │
└───────────────┬─────────────────────────┘
                │ HTTPS + JWT
┌───────────────▼─────────────────────────┐
│         Supabase (PostgreSQL)           │
│  - contacts, projects, addresses        │
│  - RLS policies (org isolation)         │
│  - JWT verification                     │
└─────────────────────────────────────────┘

Troubleshooting

"Database not connected"

Run setup again:

cd $(npm root -g)/home-automation-mcp
./scripts/setup-employee-auth.sh

"Failed to retrieve from keychain"

Check if credentials exist:

security find-generic-password -a "$USER" -s "home-automation-mcp-supabase-url"

"Account is inactive"

Contact your administrator to activate your account in Supabase:

UPDATE users SET is_active = true WHERE email = 'your-email@company.com';

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT License - see LICENSE file for details.

Support

• 📧 Technical Support: tech@modalav.co.uk
• 🐛 Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki
• 💬 Discussions: GitHub Discussions

Roadmap

• Update client/project information
• Delete clients/projects (soft delete)
• Advanced search filters
• Project status tracking
• Linux/Windows support (environment variables instead of Keychain)
• Web-based setup wizard
• Reporting and analytics tools

Developed by Costa Grigoras for Modal AV Made with ❤️ for home automation professionals