jmagar_ghome-mcp-server

jmagar_ghome-mcp-server

0
os_automation

The Google Home MCP Server allows users to control and monitor Google Home smart plugs using the Smart Home API. It features OAuth2 authentication and comprehensive error handling to ensure secure and efficient device management.

Google Home MCP Server

An MCP server implementation for controlling Google Home smart plugs through the Smart Home API.

Features

  • List all available smart plugs and their states
  • Control smart plugs (turn on/off)
  • Get real-time state of specific smart plugs
  • Automatic device state refresh
  • OAuth2 authentication with Smart Home API

Prerequisites

  1. Google Cloud Project with Smart Home API enabled
  2. Actions on Google Smart Home Action project
  3. OAuth 2.0 Client credentials for Smart Home Action
  4. Node.js 18 or higher
  5. Access to Google Home smart plugs

Setup

  1. Create a Smart Home Action:

    • Go to Actions on Google Console
    • Create a new project
    • Choose "Smart Home" as the project type
    • Configure Account Linking:
      • OAuth Client ID
      • OAuth Client Secret
      • Authorization URL
      • Token URL

  2. Set up OAuth 2.0:

    • Configure your OAuth server endpoints
    • Set up user authentication flow
    • Implement token generation/validation

  3. Install dependencies:

pnpm install

  1. Configure the server:

    • Copy config.json.example to config.json
    • Fill in your:
      • OAuth Client ID
      • OAuth Client Secret

  2. Build the server:

pnpm build
  1. Start the server:
pnpm start

Available Tools

1. List Smart Plugs

{
  name: "list_smart_plugs",
  description: "List all available smart plugs and their current states",
  response: Array<{
    id: string;
    name: string;
    state: {
      on: boolean;
      online: boolean;
    }
  }>
}

2. Control Smart Plug

{
  name: "control_smart_plug",
  description: "Turn a smart plug on or off",
  parameters: {
    deviceId: string;  // Device ID from list_smart_plugs
    state: boolean;    // true for on, false for off
  },
  response: {
    success: boolean;
    device: {
      id: string;
      name: string;
      state: {
        on: boolean;
        online: boolean;
      }
    }
  }
}

3. Get Smart Plug State

{
  name: "get_smart_plug_state",
  description: "Get the current state of a specific smart plug",
  parameters: {
    deviceId: string;  // Device ID from list_smart_plugs
  },
  response: {
    id: string;
    name: string;
    state: {
      on: boolean;
      online: boolean;
    }
  }
}

API Details

The server implements the Smart Home API intents:

  1. SYNC Intent

    • Called when users link their account
    • Reports available devices and capabilities
    • Handles device discovery

  2. QUERY Intent

    • Reports current state of devices
    • Handles state queries from Google Assistant
    • Returns online/offline status

  3. EXECUTE Intent

    • Handles device control commands
    • Executes on/off operations
    • Reports command success/failure

Error Handling

The server implements comprehensive error handling with specific error codes:

  • CONFIG_ERROR: Configuration loading or validation errors
  • API_ERROR: Errors from Smart Home API
  • DEVICE_NOT_FOUND: Device ID not found in available devices
  • COMMAND_ERROR: Error executing device command

Each error includes:

  • Error message
  • Error code
  • Detailed error information when available

Security

  • OAuth 2.0 authentication flow
  • Secure token handling
  • Request validation
  • Command authorization
  • HTTPS communication
  • Input sanitization

Development

  1. Start in development mode:
pnpm dev
  1. Run tests:
pnpm test
  1. Debug logs:
    • All API calls are logged
    • Error details are captured
    • Device state changes are tracked

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Commit your changes
  4. Push to the branch
  5. Create a Pull Request

License

MIT

ghome-mcp-server