English | 中文

supOS MCP Server

This MCP server is developed based on the typescript-sdk provided by the Model Context Protocol (MCP) protocol, allowing any client that supports the MCP protocol to use it.

It provides a series of supOS open-apis, such as querying topic tree structure, topic details, etc.

Supported APIs

Tools

1. get-topic-tree

   • Query topic tree structure menu data
   • Input:
     • key (string): Fuzzy search keyword for child nodes
     • showRec (boolean): Number of records to display
     • type (string): Search type: 1--Text search, 2--Tag search
   • Returns: topic tree structure menu data

2. get-topic-detail

   • Get details of a specific topic
   • Input:
     • topic (string): The topic path corresponding to the model
   • Returns: details of a specific topic

3. get-topic-realtime-data

   • Get real-time data of a specific topic
   • Input:
     • topic (string): The topic path corresponding to the model
   • Returns: real-time data of a specific topic

4. get-all-topic-realtime-data

   • Get and analyze real-time data of all topics
   • Returns: real-time data of all topics

5. pg-query-sql

   • Execute SQL queries on the pg database
   • Input:
     • sql (string): The SQL statement to be executed
     • params (array): SQL parameter array, optional
   • Returns: SQL query result

6. get-topic-history-data-by-pg

   • Get historical data of a specific topic
   • Input:
     • prompt (string): The prompt message input by the user for querying the historical data of the topic
   • Returns: Step-by-step prompt for querying topic historical data, convenient for step-by-step tool calls to obtain historical data

7. get-topic-query-sql

   • Get the SQL statement for querying a specific topic
   • Input:
     • prompt (string): The prompt of the SQL statement input by the user for querying the topic
   • Returns: Step-by-step prompt for querying the topic, convenient for step-by-step tool calls and generating SQL statements

Let's follow the documentation to start using it

Getting Started

System Requirements

• Node.js

Installing Client

Currently, there are many clients that support the MCP protocol, such as desktop applications like Claude for Desktop, or IDE plugins (like the Cline plugin for VSCode). To learn about supported clients, visit Model Context Protocol Client.

Here we'll use Claude for Desktop as an example.

• Download Claude for Desktop.

• Configure the required MCP server for Claude for Desktop.

• • Open your Claude for Desktop configuration in a text editor: ~/Library/Application Support/Claude/claude_desktop_config.json.
• • You can also find this configuration file location by clicking Edit Config in File -> Setting -> Developer:

• • After opening the configuration file, add the following content to claude_desktop_config.json and restart the application:
    Note: The application needs to be restarted after each modification of this configuration file for changes to take effect.

    ```json
    {
      "mcpServers": {
        "supos": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-server-supos"
          ],
          "env": {
            "SUPOS_API_KEY": "<API_KEY>",
            "SUPOS_API_URL": "<API_URL>",
            "SUPOS_MQTT_URL": "<MQTT_URL>",
            "SUPOS_PG_URL": "<PG_URL>"
          }
        }
      }
    }
    ```

• • Where API_URL is the accessible address of supOS Community Edition, you can try the entry point from here. API_KEY is the key required for open-api access. MQTT_URL can be found by visiting UNS -> MqttBroker -> Listeners to view the subscribable address.PG_URL is the URL required to access the pg database, format: postgresql://user:password@host:port/db-name

Note: The above configuration of the MCP server uses npx to pull the mcp-server-supos npm package and run it locally to provide services to clients. However, npx may have issues reading environment variable env configurations on Windows systems, so the following solutions can be adopted:

Running Service Locally

Choose one of the following two methods:

• Install mcp-server-supos locally and run it through node

1. Install

npm install mcp-server-supos -g

2. Find the installed package path, for example: "C://Users//<USER_NAME>//AppData//Roaming//npm//node_modules//mcp-server-supos//dist//index.js"

3. Modify the configuration in claude_desktop_config.json and restart the application

{
  "mcpServers": {
    "supos": {
      "command": "node",
      "args": [
        "C://Users//<USER_NAME>//AppData//Roaming//npm//node_modules//mcp-server-supos//dist//index.js"
      ],
      "env": {
        "SUPOS_API_KEY": "<API_KEY>",
        "SUPOS_API_URL": "<API_URL>",
        "SUPOS_MQTT_URL": "<MQTT_URL>",
        "SUPOS_PG_URL": "<PG_URL>"
      }
    }
  }
}

• Download and compile the repository source code locally

1. Clone the repository:

git clone https://github.com/FREEZONEX/mcp-server-supos.git

2. Install dependencies

npm ci

3. Build

npm run build

4. Modify the configuration in claude_desktop_config.json and restart the application

{
  "mcpServers": {
    "supos": {
      "command": "node",
      "args": ["<local project path>//dist//index.js"],
      "env": {
        "SUPOS_API_KEY": "<API_KEY>",
        "SUPOS_API_URL": "<API_URL>",
        "SUPOS_MQTT_URL": "<MQTT_URL>",
        "SUPOS_PG_URL": "<PG_URL>"
      }
    }
  }
}

Conclusion

That's the complete tutorial for using this service. After successful configuration, you can see the corresponding services and tools in the following panels:

Installing via Smithery

To install supOS MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @FREEZONEX/mcp-server-supos --client claude

Final Note

supOS Community Edition has integrated the open-mcp-client open-sourced by CopilotKit authors, and built-in the mcp-server-supos service, supporting ts version agent.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.