HubKit MCP Server Guide

Overview

The HubKit MCP Server is a feature that enables large language models (LLMs) like Claude to operate Gravio HubKit using the Model Context Protocol (MCP). This allows you to create, edit, and execute actions, as well as manage triggers through natural language instructions.

Required Version: This feature is available in Gravio 6.2.0 and later. On Linux and Gravio Hub X64, it is available in Gravio 6.4.0 and later.

Supported Platforms

Platform	MCP Server Support
Windows	✅ Supported
macOS	✅ Supported
Linux	✅ Supported (Gravio 6.4.0 and later)
Gravio Hub X64	✅ Supported (Gravio 6.4.0 and later)

Changed in Gravio 6.4.0: The MCP Server (port 29454) now accepts connections only from the hub itself. MCP clients on other PCs connect to https://<hub address>/mcp, over the same HTTPS as the Web UI. See Connecting from Another PC for details.

Note: On a Gravio Hub X64, an admin can turn the MCP Server on or off in Gravio Hub Settings in the Web UI (on by default).

Prerequisites

1. Installing HubKit

To use the HubKit MCP Server, HubKit must first be installed and running properly.

Windows: Download and install the Windows installer from the Gravio official website
macOS: Download and install the macOS installer from the Gravio official website
Linux / Gravio Hub X64: Install or upgrade to HubKit 6.4.0 or later, following the Gravio HubKit Installation and Upgrade Guide

2. Creating a Personal Access Token (API Key)

A Personal Access Token (API key) is required for the MCP Server to access the HubKit API.

Steps to Create a Token in Web UI

Log in to the HubKit Web UI
Select Accounts from the left menu
Find the Personal Access Token section in the logged-in user's detail screen
Click the Create Token button
In the token creation dialog, configure the following:
Token Name: A name to identify the token (e.g., "Claude Desktop MCP")
Expiration: Choose from the following options
- Never expires
- 1 day
- 1 week
- 1 month
- 6 months
- 1 year
Click the Create button
Copy and save the displayed token string in a secure location

Important: The token is only displayed at the time of creation. Once you close the screen, you cannot view it again. Make sure to copy and save it.

3. Using the Setup Guide in the Web UI (Gravio 6.4.0 and later)

From Gravio 6.4.0, the Account Management screen of the Web UI shows the configuration for Claude Desktop, Cursor and other MCP clients, ready to copy. It can also be opened from the screen shown right after you create a token. On Windows and Mac hubs, you can also download and install the extension package (.mcpb) for Claude Desktop. See Web UI Guide: AI Client Integration (MCP) for details.

Note: The endpoint URL shown in the setup guide (http://<hub address>:29454/mcp) can only be reached from the hub itself. To connect from another PC, use the configuration in Connecting from Another PC.

Integration with Claude Desktop

Claude Desktop Configuration

To use the HubKit MCP Server with Claude Desktop, add the MCP Server to Claude Desktop's configuration file.

Configuration File Location

OS	Configuration File Path
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`

Configuration Example

For macOS:

When HubKit starts, the MCP Server automatically starts at http://127.0.0.1:29454/mcp. Claude Desktop on the same PC as the hub connects to this endpoint using mcp-remote (to connect from another PC, see Connecting from Another PC).

{
  "mcpServers": {
    "GravioACS": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:29454/mcp",
        "--allow-http",
        "--header",
        "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN_HERE"
      ]
    }
  }
}

Note: - Replace YOUR_PERSONAL_ACCESS_TOKEN_HERE with the actual token created in Web UI (a string starting with ghk_at_) - Authentication is done only via the Authorization: Bearer header (the env section is not required)

About mcp-remote

mcp-remote is an npm package for connecting to remote MCP servers via HTTP.

Prerequisites: - Node.js must be installed - Installing Node.js also installs the npx command

Usage:

Using npx (Recommended)
npx mcp-remote ... automatically downloads and runs the package
No pre-installation required
Global Installation (Alternative)
Pre-install with npm install -g mcp-remote
Then you can specify "command": "mcp-remote" directly in the configuration file

For Windows:

{
  "mcpServers": {
    "GravioACS": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:29454/mcp",
        "--allow-http",
        "--header",
        "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN_HERE"
      ]
    }
  }
}

Connecting from Another PC

From Gravio 6.4.0, the MCP Server (port 29454) accepts connections only from the hub itself. To connect to a Linux or Gravio Hub X64 hub, or to a Windows or Mac hub running on another PC, connect to /mcp over the same HTTPS (port 443) as the Web UI.

For Claude Desktop:

{
  "mcpServers": {
    "GravioACS": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<hub address>/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_PERSONAL_ACCESS_TOKEN_HERE",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

Note: - Replace <hub address> with the host name or IP address you use to open the Web UI - Claude Desktop re-splits arguments that contain spaces, so the authorization header is passed in the AUTH_HEADER environment variable - NODE_TLS_REJECT_UNAUTHORIZED skips verification of the hub's self-signed certificate. It is not needed when the hub has a proper server certificate (such as one from Let's Encrypt)

For Cursor and other clients that support Streamable HTTP:

Item	Value
Endpoint URL	`https://<hub address>/mcp`
Authorization header	`Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN_HERE`

Verification After Configuration

Restart Claude Desktop
Start a new chat and verify that the MCP Server is recognized
Test by entering questions or operation instructions related to Gravio

Available Features

The HubKit MCP Server allows you to operate the following features using natural language:

Feature	Description
Get Action List	Retrieve the list of actions registered in HubKit
Get Action Details	Retrieve the complete JSON data for a specific action
Create Action	Create a new action
Update Action	Update an existing action
Execute Action	Execute an action immediately and get the result
Validate Action	Validate the correctness of action JSON

Feature	Description
Get Trigger List	Retrieve the list of timer triggers and event triggers
Create/Update Trigger	Create a new trigger or update an existing trigger
Enable/Disable Trigger	Toggle trigger on/off
Validate Trigger	Validate the correctness of trigger JSON

Feature	Description
Get Component Schema	Retrieve the JSON schema for a specific component
Get Function Documentation	Retrieve documentation for functions available in Pre/PostMapping. From Gravio 6.4.0, only the functions the connected hub actually supports are offered
Get Layout Information	Retrieve information about areas, layers, and devices
Get Base Properties	Retrieve the list of available base properties

Usage Examples

Example 1: Creating a Simple Action

You can give instructions like this in Claude Desktop:

Create an action that sends "Good morning" to Slack every day at 9 AM.

The MCP Server will automatically: 1. Retrieve the schema for necessary components (such as HTTPRequest) 2. Build the action JSON 3. Execute validation 4. Save to HubKit after confirmation

Example 2: Setting Up a Trigger

Set up a trigger that sends an alert email when the temperature sensor value exceeds 30 degrees.

Example 3: Checking and Editing Existing Actions

Show me the list of currently registered actions.
Check the contents of the "Regular Report Sending" action and change the destination email address.

Troubleshooting

Common Problems and Solutions

Cannot Connect to MCP Server

Check if HubKit is running
Windows: Check the Gravio icon in the system tray
macOS: Check the Gravio icon in the menu bar
Check the Personal Access Token
Verify that the token is correctly configured
Check if the token has expired
Check the token specification
Verify that the token is correctly specified in the Authorization: Bearer header in Claude Desktop settings
Verify that the token is in the correct format starting with ghk_at_
Check the URL you connect to (Gravio 6.4.0 and later)
When connecting from a PC other than the hub, check that you connect to https://<hub address>/mcp, not http://<hub address>:29454/mcp (Connecting from Another PC)
On a Gravio Hub X64, check that the MCP Server is not turned off in Gravio Hub Settings in the Web UI

Authentication Error Occurs

PAT was invalid

If this error is displayed: 1. Create a new Personal Access Token in Web UI 2. Update the token in the Authorization: Bearer header in Claude Desktop's configuration file 3. Restart Claude Desktop

Action Execution Fails

Check the component settings within the action
Check the connection settings to external services (Slack, mail server, etc.)
Check the HubKit logs to understand the error details

Checking Logs

MCP Server logs are output to the following locations:

OS	Log File Location
Windows	`%PROGRAMDATA%\Hubkit\mcp\logs\`
macOS	`/Library/Application Support/HubKit/mcp/logs/`

To increase debug information, change MinLogLevel to debug in the configuration file.

Security Considerations

Managing Personal Access Tokens
Store tokens in a secure location
Revoke tokens that are no longer needed from Web UI
Regularly updating tokens is recommended
Usage Environment
The MCP Server is intended for use in development environments
Use in production environments is not recommended