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.

Supported Platforms

Important: The HubKit MCP Server is only available on Windows and macOS versions of HubKit. The MCP Server feature is not available on Linux versions of HubKit.

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

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

1. Log in to the HubKit Web UI

2. Select Accounts from the left menu

3. Find the Personal Access Token section in the logged-in user's detail screen

4. Click the Create Token button

5. In the token creation dialog, configure the following:

6. Token Name: A name to identify the token (e.g., "Claude Desktop MCP")

7. Expiration: Choose from the following options

   • Never expires
   • 1 day
   • 1 week
   • 1 month
   • 6 months
   • 1 year

8. Click the Create button

9. 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.

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

Configuration Example

For macOS:

When HubKit starts, the MCP Server automatically starts at http://localhost:29454/mcp. Claude Desktop connects to this endpoint using mcp-remote.

{
  "mcpServers": {
    "GravioACS": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost: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:

1. Using npx (Recommended)
2. npx mcp-remote ... automatically downloads and runs the package

3. No pre-installation required

4. Global Installation (Alternative)

5. Pre-install with npm install -g mcp-remote
6. Then you can specify "command": "mcp-remote" directly in the configuration file

For Windows:

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

Verification After Configuration

1. Restart Claude Desktop

2. Start a new chat and verify that the MCP Server is recognized

3. 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:

Action (ACS) Related

Trigger Related

Component and Function Related

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

1. Check if HubKit is running
2. Windows: Check the Gravio icon in the system tray

3. macOS: Check the Gravio icon in the menu bar

4. Check the Personal Access Token

5. Verify that the token is correctly configured

6. Check if the token has expired

7. Check the token specification

8. Verify that the token is correctly specified in the Authorization: Bearer header in Claude Desktop settings
9. Verify that the token is in the correct format starting with ghk_at_

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:

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

Security Considerations

1. Managing Personal Access Tokens
2. Store tokens in a secure location
3. Revoke tokens that are no longer needed from Web UI

4. Regularly updating tokens is recommended

5. Usage Environment

6. The MCP Server is intended for use in development environments
7. Use in production environments is not recommended

Related Documentation

• Gravio HubKit Guide
• Action Flow Guide
• Trigger Manual
• Gravio API Documentation