Package Exports

home-automation-mcp
home-automation-mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (home-automation-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 = '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

Completed in v1.1.0

Update client/project information
Get comprehensive client/project details
Search projects with filters
Maintenance management with visit scheduling
Product/equipment tracking with warranty management
Document management with expiry tracking
Company management with contact linking
Notes system for contacts/companies/projects
Service credentials management with version history
Photo/media attachment and organization
Custom fields with automatic version tracking
Address update functionality
Project contacts management (multiple contacts per project)
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