Content
# supOS MCP Server
This MCP server is developed based on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) protocol using the `typescript-sdk`, allowing any client that supports the MCP protocol to utilize it.
It provides a series of open APIs for supOS, such as querying the topic tree structure, topic details, and more.
## Supported APIs
### Tools
1. `get-model-topic-tree`
- Query the 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-model-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 for a specific topic
- Input:
- `topic` (string): The topic path corresponding to the model
- Returns: Real-time data for a specific topic
4. `get-all-topic-realtime-data`
- Get and analyze real-time data for all topics
- Returns: Real-time data for all topics
***Now let's use the documentation together***
## Getting Started
### System Requirements
- Node.js
### Installing the Client
Currently, there are many clients that support the MCP protocol, such as the desktop application `Claude for Desktop`, or some plugins for IDEs (like the `Cline` plugin for `VSCode`). To learn about supported clients, you can visit [Model Context Protocol Client](https://modelcontextprotocol.io/clients).
Here, we will take `Claude for Desktop` as an example.
- Download [Claude for Desktop](https://claude.ai/download).
- 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 the configuration file location by clicking `File -> Setting -> Developer` and then `Edit Config`:



- - After opening the configuration file, add the following content to `claude_desktop_config.json` and restart the application:
*Note: You need to restart the application every time you modify this configuration file for the 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>"
}
}
}
}
```
- - Here, `API_URL` is the accessible [supOS Community Edition](https://supos-demo.supos.app/) address. You can obtain the `API_KEY` by logging into the Community Edition, navigating to `DataModeling -> View details of a specific topic -> Data Operation -> Fetch`, and copying the corresponding ApiKey. The `MQTT_URL` can be found by visiting `UNS -> MqttBroker -> Listeners` to see the subscribable addresses.
**Note: The above configuration for the MCP server uses `npx` to pull the `mcp-server-supos` npm package and run it locally to provide services to the client. However, `npx` may encounter issues reading the `env` configuration on `Windows` systems, so you can use the following method to resolve this:**
### Running the Service Locally
You can choose one of the following two methods:
- Install `mcp-server-supos` locally and run it with Node
1. Install
```bash
npm install mcp-server-supos -g
```
2. Find the installation 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
```json
{
"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>"
}
}
}
}
```
- Download the source code of this repository, compile and execute it locally
1. Clone the repository:
```bash
git clone https://github.com/FREEZONEX/mcp-server-supos.git
```
2. Install dependencies
```bash
npm ci
```
3. Compile
```bash
npm run build
```
4. Modify the configuration in `claude_desktop_config.json` and restart the application
```json
{
"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>"
}
}
}
}
```
### Conclusion
This concludes the tutorial on using this service. Once configured successfully, you can see the corresponding services and tools in the following panel:



### Finally
The [supOS Community Edition](https://supos-demo.supos.app/) has integrated the open-source [open-mcp-client](https://github.com/CopilotKit/open-mcp-client) by the author of `CopilotKit`, and has built-in support for the `mcp-server-supos` service, as well as support for the TypeScript version of `agent`. The source code can be accessed at [supOS-CE-McpClient](https://github.com/FREEZONEX/supOS-CE-McpClient).
Connection Info
You Might Also Like
Time
Obtaining current time information and converting time between different...
bytebot
Bytebot is a self-hosted AI desktop agent that automates computer tasks...
inbox-zero
The world's best AI personal assistant for email. Open source app to help...
DesktopCommanderMCP
This is MCP server for Claude that gives it terminal control, file system...
ClaudeComputerCommander
This is an MCP server that provides terminal control, file system search,...
astron-rpa
Agent-ready RPA suite with out-of-the-box automation tools. Built for...