spruthub-mcp-server

shady2k/spruthub-mcp-server

3.1

If you are the rightful owner of spruthub-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Spruthub MCP Server is designed to facilitate interaction with Spruthub smart home devices through a WebSocket connection, enabling control and management via MCP-compatible clients like Claude.

Tools
4
Resources
0
Prompts
0

Spruthub MCP Server

npm version npm

A Model Context Protocol (MCP) server for controlling Sprut.hub smart home devices. This server provides Claude and other MCP-compatible clients with dynamic access to the complete Sprut.hub JSON-RPC API through schema autodiscovery.

Features

  • Dynamic API Discovery - Automatically discovers and exposes all available Spruthub JSON-RPC methods
  • Schema Validation - Built-in parameter validation and documentation for all API methods
  • Full API Coverage - Access to all Spruthub functionality including devices, rooms, scenarios, and system administration
  • WebSocket Connection - Secure connection to Spruthub server with authentication
  • Method Categories - Organized API methods by category (hub, accessory, scenario, room, system)
  • Real-time Schema Updates - Schema information updated with spruthub-client library versions
  • Structured Responses - JSON-formatted responses optimized for AI integration

Installation

Using npx (Recommended)

Run the MCP server directly using npx:

npx spruthub-mcp-server

Using Claude Desktop

Add to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "spruthub": {
      "command": "npx",
      "args": ["spruthub-mcp-server"],
      "env": {
        "SPRUTHUB_WS_URL": "wss://your-spruthub-server.com/ws",
        "SPRUTHUB_EMAIL": "your-email@example.com",
        "SPRUTHUB_PASSWORD": "your-password",
        "SPRUTHUB_SERIAL": "your-device-serial"
      }
    }
  }
}

Development

For development or local modifications:

git clone https://github.com/shady2k/spruthub-mcp-server.git
cd spruthub-mcp-server
npm install

Usage

As an MCP Server

Add this server to your MCP client configuration. For Claude Desktop, add to your claude_desktop_config.json:

Using npm package (recommended):
{
  "mcpServers": {
    "spruthub-mcp-server": {
      "command": "npx",
      "args": [
        "spruthub-mcp-server@1.3.9"
      ],
      "env": {
        "SPRUTHUB_WS_URL": "ws://192.168.0.100/spruthub",
        "SPRUTHUB_EMAIL": "your_email@example.com",
        "SPRUTHUB_PASSWORD": "your_password",
        "SPRUTHUB_SERIAL": "AAABBBCCCDDDEEEF"
      }
    }
  }
}
For local development:
{
  "mcpServers": {
    "spruthub-mcp-server": {
      "command": "node",
      "args": ["/path/to/spruthub-mcp-server/src/index.js"],
      "env": {
        "SPRUTHUB_WS_URL": "ws://192.168.0.100/spruthub",
        "SPRUTHUB_EMAIL": "your_email@example.com", 
        "SPRUTHUB_PASSWORD": "your_password",
        "SPRUTHUB_SERIAL": "AAABBBCCCDDDEEEF"
      }
    }
  }
}

Note: Replace the environment variables with your actual Spruthub server details:

  • SPRUTHUB_WS_URL: WebSocket URL of your Spruthub server
  • SPRUTHUB_EMAIL: Your Spruthub account email
  • SPRUTHUB_PASSWORD: Your Spruthub account password
  • SPRUTHUB_SERIAL: Your Spruthub hub serial number

Security Best Practice: For sensitive values like SPRUTHUB_PASSWORD, consider using your system's environment variables instead of hardcoding them in the config file:

{
  "mcpServers": {
    "spruthub-mcp-server": {
      "command": "npx",
      "args": ["spruthub-mcp-server@1.3.9"],
      "env": {
        "SPRUTHUB_WS_URL": "ws://192.168.0.100/spruthub",
        "SPRUTHUB_EMAIL": "your_email@example.com",
        "SPRUTHUB_PASSWORD": "$SPRUTHUB_PASSWORD",
        "SPRUTHUB_SERIAL": "AAABBBCCCDDDEEEF"
      }
    }
  }
}

Then set the password in your system environment:

export SPRUTHUB_PASSWORD="your_actual_password"

Available Tools

This server provides three core tools that give you access to the complete Spruthub JSON-RPC API:

spruthub_list_methods

Discover all available Spruthub API methods with their descriptions and categories.

Parameters:

  • category (optional): Filter methods by category (hub, accessory, scenario, room, system)

Example usage: Start here to explore what's available in your Spruthub system.

spruthub_get_method_schema

Get detailed schema information for any API method, including parameters, return types, and examples.

Parameters:

  • methodName (required): The method name to get schema for (e.g., accessory.search, characteristic.update)

Important: Always call this tool before using spruthub_call_method to understand the exact parameter structure required.

spruthub_call_method

Execute any Spruthub JSON-RPC API method with the provided parameters.

Parameters:

  • methodName (required): The API method to call
  • parameters (optional): Method parameters as defined in the method's schema

Critical: You MUST call spruthub_get_method_schema first to understand the parameter structure. Never guess parameters.

Common Workflows

  1. Explore your system:

    spruthub_list_methods → spruthub_get_method_schema → spruthub_call_method

  2. Control devices:

    spruthub_get_method_schema(methodName: "characteristic.update")
→ spruthub_call_method(methodName: "characteristic.update", parameters: {...})

  3. Browse by category:

    spruthub_list_methods(category: "accessory") → Get device-related methods
spruthub_list_methods(category: "scenario") → Get automation methods

Efficient API Usage

The schema-based approach provides efficient access to Spruthub functionality:

Recommended Workflow

  1. Discovery Phase: Use spruthub_list_methods to explore available functionality
  2. Schema Phase: Use spruthub_get_method_schema to understand method requirements
  3. Execution Phase: Use spruthub_call_method with proper parameters

Best Practices

  • Filter by category when exploring: Use category parameter in spruthub_list_methods
  • Always get schema first: Never guess API parameters - use spruthub_get_method_schema
  • Use specific methods: The API provides targeted methods for efficient operations
  • Check method categories:
    • hub - Hub management and status
    • accessory - Device discovery and control
    • scenario - Automation and scenes
    • room - Room management
    • system - System administration

Schema-Driven Development

Each API method includes:

  • Complete parameter specifications
  • Return type definitions
  • Usage examples
  • REST API mapping (where available)
  • Category classification

Development

# Install dependencies
npm install

# Run in development mode with auto-reload
npm run dev

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

Environment Variables

Connection Settings

  • LOG_LEVEL: Set logging level (default: 'info')
  • SPRUTHUB_WS_URL: WebSocket URL for Spruthub server (required if auto-connecting)
  • SPRUTHUB_EMAIL: Email for authentication (required if auto-connecting)
  • SPRUTHUB_PASSWORD: Password for authentication (required if auto-connecting)
  • SPRUTHUB_SERIAL: Device serial number (required if auto-connecting)

Logging Settings

  • LOG_LEVEL: Set logging level (info, debug, warn, error) (default: 'info')

License

MIT