home-automation-mcp

v1.1.0

Published

9 months ago

MCP server for home automation business - manage clients and projects with Supabase backend

0High
0Medium
0Low

grego360

mcp model-context-protocol home-automation client-management crm project-management supabase claude ai-assistant

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
🏢 Company Management (New in v1.1.0) - Manage business clients, link contacts, track decision-makers
📊 Project Management - Track projects with unique project codes and client linking
🔧 Maintenance Management (New in v1.1.0) - Schedule visits, track maintenance plans, find sales opportunities
📦 Product Management (New in v1.1.0) - Track installed equipment, warranties, and product recalls
📄 Document Management (New in v1.1.0) - Attach project documents, track certificate expiry
📝 Notes System (New in v1.1.0) - Add notes to contacts, companies, and projects with tagging
🔑 Service Credentials (New in v1.1.0) - Manage service accounts, track expiry, version history
📸 Photo Management (New in v1.1.0) - Attach photos to projects and products
🎛️ Custom Fields (New in v1.1.0) - Add project-specific fields with automatic version tracking
🏠 Address Management (New in v1.1.0) - Update and manage client and project addresses
👥 Project Contacts (New in v1.1.0) - Manage multiple contacts per project with roles
🔍 Advanced Search (New in v1.1.0) - Filter by date ranges, status, type, location, and more
🔐 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

Manage Companies

You: Create a company called "Tech Solutions Ltd" in the IT Services industry

Claude: ✅ Company created successfully

You: Link John Smith to Tech Solutions Ltd as the Technical Director

Claude: ✅ John Smith added to Tech Solutions Ltd as Technical Director

You: Show me all companies in the IT Services industry

Claude: Found 5 companies in IT Services:
- Tech Solutions Ltd (Primary Contact: John Smith)
- Digital Systems UK (Primary Contact: Jane Doe)
...

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 with advanced filters
- Full-text search on names and account numbers
- Filter by signup year or date range
- Filter by email, phone, or city
- Limit results (default 10)
- Shows addresses in results
- New: Advanced date range filtering (date_from, date_to)
- New: Email and phone partial match
- New: City-based filtering
get_client_details - Get comprehensive client information by account number
- Shows all addresses with primary indicator
- Lists all projects with status and type
- Contact information and join date
update_client - Update existing client information
- Update first_name, last_name, email, phone
- Search by account number

Company Management (New in v1.1.0)

create_company - Create new company/business client with optional address
- Separate business clients from individual contacts
- Track company website, email, phone
- Link to industry and status
- Add company address on creation
find_companies - Search companies by name, industry, or status
- Full-text search on company names
- Filter by industry or status
- Configurable limit (default 10)
- Shows industry and status in results
get_company_details - Get comprehensive company information by ID
- Shows all linked contacts with roles/departments
- Lists all company addresses with primary indicator
- Displays industry and status
- Contact information and website
update_company - Update existing company information
- Update name, website, email, phone
- Change industry or status
- Add or update notes
- Search by company ID
add_company_contact - Link a contact to a company with role and department
- Specify role (e.g., Director, Manager, Engineer)
- Assign department (e.g., Sales, Technical, Finance)
- Track relationship between contacts and companies
- Supports multiple contacts per company
remove_company_contact - Unlink a contact from a company
- Remove company-contact relationship
- Maintain contact record separately
- Clean company-contact junction table
find_companies_by_industry - Find all companies in a specific industry
- Target vertical markets
- Industry-specific marketing campaigns
- Shows primary contacts for outreach
find_companies_by_status - Find all companies with a specific status
- Filter by active, inactive, prospect, etc.
- Sales pipeline management
- Account health monitoring
set_company_primary_contact - Designate primary decision-maker for a company
- Mark main point of contact
- Only one primary contact per company
- Important for account management
get_company_projects - Get all projects associated with a company
- Shows projects for all company contacts
- Displays project status and type
- Useful for account review and upselling

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
find_projects - Search projects with advanced filters
- Filter by client name or account number
- Shows client, status, type, and address
- Configurable limit (default 10)
- New: Search in project title and description
- New: Filter by project status or type
- New: Date range filtering (created date)
get_project_details - Get comprehensive project information by project code
- Client details with address
- Project addresses
- Installed products (brand, model, serial, IP, location)
- Additional contacts with roles
update_project - Update existing project information
- Update title and description
- Search by project code

Maintenance Management (New in v1.1.0)

get_maintenance_due - Get maintenance visits due this week, this month, or overdue
- Filter by technician
- Shows client and project details
- Displays visit status and schedule
schedule_maintenance - Schedule a maintenance visit for a project
- Requires existing maintenance plan
- Set date and optional time
- Add notes for technician
get_client_maintenance - Get maintenance plan and visit history for a project
- Shows plan type and details
- Lists all scheduled and completed visits
- Identifies sales opportunities
find_projects_without_maintenance - Find projects without maintenance plans
- Sales opportunity identification
- Shows client contact info
- Configurable limit
complete_maintenance_visit - Mark a maintenance visit as completed
- Add completion notes
- Set completion percentage
- Automatic timestamp

Product Management (New in v1.1.0)

add_project_product - Add installed equipment/product to a project
- Track brand, model, serial number
- Store IP address and login credentials (encrypted)
- Set warranty expiry date
- Record installation location
update_project_product - Update product details
- Update IP address, location, warranty
- Change credentials securely
- Add notes
find_products_warranty_expiring - Find products with expiring warranties
- Configurable days until expiry
- Shows client contact info
- Upgrade opportunity identification
search_product_catalog - Search common products catalog
- Filter by brand or category
- See typical prices
- View usage statistics
find_product_installations - Find all installations of a specific product
- Critical for product recalls
- Firmware update campaigns
- Shows client addresses and contacts

Document Management (New in v1.1.0)

add_project_document - Attach document to project
- Supports contracts, manuals, certificates, warranties, photos
- Set expiry dates for certificates
- Tag system for organization
- Store URLs or file paths
find_expiring_documents - Find certificates/licenses expiring soon
- Configurable days until expiry
- Filter by document type
- Shows client contact info for renewal
get_project_documents - List all documents attached to a project
- Optional filter by document type
- Shows upload dates and expiry dates
- Displays tags and descriptions

Notes Management (New in v1.1.0)

create_note - Create a note for any entity (contact, company, or project)
- Add title and content
- Categorize by note type (follow_up, issue, decision, general)
- Tag notes for organization
- Attach to contacts, companies, or projects
get_entity_notes - Get all notes for a specific entity
- Filter by entity type and ID
- Shows only active notes
- Sorted by most recent
update_note - Update existing note
- Modify title, content, type, or tags
- Automatic timestamp tracking
delete_note - Soft delete a note
- Note remains in database but marked inactive
- Can be restored if needed
search_notes - Search notes by content or tags
- Full-text search on title and content
- Filter by tags, entity type, or note type
- Configurable result limit

Service Credentials Management (New in v1.1.0)

add_service_credential - Add service account credentials to a project
- Store streaming services, cloud accounts, etc.
- Track service name, URL, category
- Store username, email, encrypted password
- Set expiry dates for renewals
get_project_credentials - Get all service credentials for a project
- Shows active credentials only
- Organized by service category
- Includes expiry warnings
update_service_credential - Update credential details
- Automatic version history via database trigger
- Track all changes with timestamps
- Update expiry dates
find_expiring_credentials - Find credentials expiring soon
- Configurable days until expiry (default 30)
- Shows client contact info for renewals
- Prevents service interruptions

Photo Management (New in v1.1.0)

add_project_photo - Add photos to projects
- Site photos, before/after shots
- Label with description
- Track when photo was taken
- Store URL or file path
get_project_photos - List all photos for a project
- Sorted by date taken (newest first)
- Shows labels and URLs
- Easy reference for project history
add_product_photo - Add photos to specific equipment
- Serial number plates, installation positions
- Link directly to installed products
- Useful for warranty claims and support

Custom Fields Management (New in v1.1.0)

add_custom_field - Add project-specific custom fields
- Four field types: text, number, date, boolean
- Group fields by category (Access, Technical, Client Info)
- Set display order
- Mark fields as required
get_custom_fields - Get all custom fields for a project
- Optional filter by field group
- Organized by categories
- Shows field IDs for updates
update_custom_field - Update custom field values
- Automatic version history tracking
- Database trigger saves all changes
- Update any field property

Address Management (New in v1.1.0)

update_address - Update existing address information
- Modify first line, second line, city, postcode, country
- Update apartment/flat numbers
- Add or modify address notes
- Maintains address history through timestamps
- Affects all entities (clients, projects) linked to address

Project Contacts Management (New in v1.1.0)

add_project_contact - Add additional contacts to projects
- Link multiple contacts beyond the main client
- Assign roles (Property Manager, Tenant, Decision Maker, etc.)
- Add notes about contact relationship
- Useful for properties with multiple stakeholders
remove_project_contact - Remove additional contact from project
- Unlink secondary contacts
- Maintains main client relationship
- Clean junction table entries
get_project_contacts - List all contacts associated with a project
- Shows all linked contacts with roles
- Displays primary contact indicator
- Includes contact details and notes
- Essential for project communication
set_project_primary_contact - Change primary contact for project
- Designate new main point of contact
- Only one primary contact per project
- Important for billing and communication

Utilities

generate_account_number - Generate client account numbers
generate_project_id - Generate project codes
validate_account_number - Validate account number format
get_server_info - Check MCP server version and status

Database Schema

The server expects a Supabase database with the following tables:

Core Tables

contacts - Client/contact records
companies - Business client records
company_contacts - Junction table linking contacts to companies with roles
company_addresses - Junction table linking companies to addresses
company_industries - Industry lookup (IT Services, Security, etc.)
company_statuses - Status lookup (active, prospect, inactive, etc.)
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

Employee authenticates with email/password
Supabase issues JWT token
Token stored in macOS Keychain
All API calls include JWT
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:

Your Supabase URL
Valid employee credentials in your database
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/grego360/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 (61 tools)       │    │
│  │  Client: create, find, update   │    │
│  │  Company: manage, link contacts │    │
│  │  Project: create, find, update  │    │
│  │  Maintenance: schedule, track   │    │
│  │  Products: add, update, search  │    │
│  │  Documents: attach, track expiry│    │
│  │  Notes: create, search, tag     │    │
│  │  Credentials: manage, track exp │    │
│  │  Photos: attach to projects     │    │
│  │  Custom Fields: typed, versioned│    │
│  │  Addresses: update, manage      │    │
│  │  Project Contacts: link, manage │    │
│  │  Advanced Search: multi-criteria│    │
│  └──────────────┬──────────────────┘    │
│                 │                        │
│  ┌──────────────▼──────────────────┐    │
│  │  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 = '[email protected]';

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT License - see LICENSE file for details.

Support

📧 Technical Support: [email protected]
🐛 Issues: GitHub Issues
📖 Documentation: GitHub Wiki
💬 Discussions: GitHub Discussions

Roadmap

Completed in v1.1.0

[x] Update client/project information
[x] Get comprehensive client/project details
[x] Search projects with filters
[x] Maintenance management with visit scheduling
[x] Product/equipment tracking with warranty management
[x] Document management with expiry tracking
[x] Company management with contact linking
[x] Notes system for contacts/companies/projects
[x] Service credentials management with version history
[x] Photo/media attachment and organization
[x] Custom fields with automatic version tracking
[x] Address update functionality
[x] Project contacts management (multiple contacts per project)
[x] Advanced search filters (date ranges, multiple criteria)

Planned for Future Releases

[ ] Maintenance templates and checklists
[ ] Client visit requests and scheduling
[ ] Staff management and permissions
[ ] Forms and templates management
[ ] Delete clients/projects (soft delete)
[ ] Project status workflow transitions
[ ] 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