supOS

You can query topic structures, details, and real-time data through the supOS MCP Server, which exposes a set of open-apis for working with topic trees and their data. It is built to be used by any client that supports the MCP protocol, enabling streamlined access to topic-related information and SQL-backed history and queries.

How to use

Connect to the MCP server using a client that supports MCP, then call the available endpoints to explore topics, retrieve details, and fetch real-time or historical data. The server provides endpoints for topic-tree queries, topic details, real-time topic data, and SQL-backed operations against the underlying database. Use your client’s normal flow to authenticate and pass the required inputs for each endpoint.

How to install

Prerequisites you need before you begin:

• Node.js installed on your system
• A client that supports MCP (for example Claude for Desktop)
• Internet access to install packages and fetch dependencies

Choose one of the following runtime methods to start the MCP server. Use the exact commands shown to avoid configuration issues.

# Method A: Run via npx (temporary/project-local use)
npx -y mcp-server-supos

{
  "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>"
      }
    }
  }
}

# Method B: Install locally and run with node
npm install mcp-server-supos -g

# Locate the installed path and start using node with the index
# Example path will vary by system
node "C://Users//<USER_NAME>//AppData//Roaming//npm//node_modules//mcp-server-supos//dist//index.js"

# Method C: Build from source and run from dist
git clone https://github.com/FREEZONEX/mcp-server-supos.git
npm ci
npm run build

# Start from the built dist file
node "<local project path>//dist//index.js"

{
  "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>"
      }
    }
  }
}

Additional notes

Environment variables shown here are required to connect to your supOS MCP Server endpoints. Replace placeholder values with your actual API key, API URL, MQTT URL, and PostgreSQL URL. Restart the client after applying any configuration changes to ensure the settings take effect.

Security and best practices

Keep API keys and database credentials secure. Do not commit sensitive values to source control. Use environment-specific configuration and rotate credentials regularly. Ensure your MCP client and server are reachable only within trusted networks and use HTTPS for API endpoints when available.

Examples of common workflows

1. Retrieve the topic tree to understand available topics and their structure.
2. Request details for a specific topic to learn its properties.
3. Fetch real-time data for a topic to monitor current activity.
4. Run SQL-based queries against the PostgreSQL database to obtain historical data or generate custom insights.

Available tools

get-topic-tree

Query the topic tree structure data with optional fuzzy keyword, display count, and search type.

get-topic-detail

Retrieve detailed information for a specific topic path.

get-topic-realtime-data

Fetch real-time data for a specific topic path.

get-all-topic-realtime-data

Collect and analyze real-time data across all topics.

pg-query-sql

Execute SQL statements against the PostgreSQL database and return results.

get-topic-history-data-by-pg

Obtain historical data prompts to guide step-by-step data retrieval for a topic.

get-topic-query-sql

Generate SQL statements for querying a specific topic via prompts.