ThingsPanel MCP

MCP (Model Context Protocol) server for ThingsPanel IoT platform.

English | 中文

This MCP server integrates ThingsPanel IoT platform with AI models like Claude, GPT, and others that support the Model Context Protocol. It provides a standardized way for AI models to:

• Query device information and status from ThingsPanel
• Retrieve historical device data for analysis
• Manage devices (create, update, delete)
• Access product catalogs and templates
• Monitor and respond to alarms and notifications
• Send commands to IoT devices through ThingsPanel

By using this MCP server, AI assistants can directly interact with your IoT devices and data in a secure, controlled manner, enabling powerful use cases like natural language device control, data visualization requests, anomaly detection, and intelligent automation based on device data.

Who is this for?

Target Audience

• IoT Solution Developers: Engineers and developers who are building solutions on the ThingsPanel IoT platform and want to integrate AI capabilities
• AI Integration Specialists: Professionals looking to connect AI models with IoT systems
• System Administrators: IT staff responsible for managing IoT infrastructure who want to enable AI-powered analytics and control
• Product Teams: Teams building products that combine IoT and AI functionalities

Problems Solved

• Integration Complexity: Eliminates the need to build custom integration between AI models and IoT platforms
• Standardized Access: Provides a consistent interface for AI models to interact with IoT data and devices
• Security Control: Manages authentication and authorization for AI access to IoT systems
• Technical Barrier Reduction: Lowers the technical barrier for adding AI capabilities to existing IoT deployments

Ideal Use Cases

• Natural Language IoT Control: Enable users to control devices using natural language through AI assistants
• Intelligent Data Analysis: Allow AI models to access and analyze IoT sensor data for insights
• Anomaly Detection: Connect AI models to device data streams for real-time anomaly detection
• Predictive Maintenance: Enable AI-driven predictive maintenance by providing access to device history
• Automated Reporting: Create systems that can generate reports and visualizations of IoT data on request
• Operational Optimization: Use AI to optimize device operations based on historical patterns

Features

• Device Management
  • List devices with pagination and filtering
  • Get device details by ID
  • Create new devices
  • Update existing devices
  • Delete devices
  • Batch device operations
  • Device grouping
• Data Retrieval and Analysis
  • Query historical device data
  • Filter by time range
  • Filter by specific attributes
  • Get latest device data
  • Statistical analysis of device data
  • Data visualization endpoints
• Product Management
  • List products with pagination
  • Get product details
  • Create and update products
  • Product template management
• Alarm and Notification
  • List device alarms
  • Filter alarms by status, severity, and time
  • Create and update alarms
  • Acknowledge and resolve alarms
  • Configure alarm rules
• Command and Control
  • Send commands to devices
  • Schedule device actions
  • Batch command operations
• Integration
  • Model Context Protocol (MCP) support
  • Transport options (stdio, SSE)
  • Docker container support
  • Webhook support
  • Third-party API integrations

The list of tools is configurable, allowing you to enable or disable specific functionalities based on your needs or context window constraints.

Installation

Or install from source:

Configuration

Configuration is done via environment variables:

• THINGSPANEL_URL: ThingsPanel API URL (default: http://thingspanel.io/)
• THINGSPANEL_API_KEY: Your ThingsPanel API key

Setting up your API key

The API key must be set correctly for authentication with the ThingsPanel platform. ThingsPanel uses the x-api-key header for authentication.

You can set your API key in several ways:

1. Environment variable (recommended):
   export THINGSPANEL_API_KEY=your_api_key
2. Inline with command:
   THINGSPANEL_API_KEY=your_api_key thingspanel-mcp
3. In your .env file: Create a .env file in the project directory:
   THINGSPANEL_URL=http://thingspanel.io/ THINGSPANEL_API_KEY=your_api_key

To verify your API key works correctly, you can test it with a direct API call:

Usage

Start the MCP server:

This will start the server using stdio for transport by default. You can also use SSE:

To see all available options:

Docker Usage

You can also run ThingsPanel MCP in a Docker container:

Using Docker Compose (Recommended)

1. Set your API key in the environment:
   export THINGSPANEL_API_KEY=your_api_key
2. Start the services:
   docker-compose up -d

This will start both the ThingsPanel MCP server and the MCP Inspector for debugging.

Using Docker Directly

1. Build the Docker image:
   docker build -t thingspanel-mcp .
2. Run the container:
   docker run -p 8000:8000 -e THINGSPANEL_API_KEY=your_api_key thingspanel-mcp

Manual Testing

First, make sure you have set the API key as an environment variable:

Then start the MCP Inspector. You have two options:

1. Using the built-in inspect command (recommended):

2. Using npx directly:

After starting the Inspector, navigate to http://localhost:5173 in your browser.

List Devices

Get Device Details

Create Device

Expected response:

Update Device

Expected response:

Delete Device

Expected response:

Debugging with MCP Inspector

The MCP Inspector is a useful tool for debugging and testing your MCP server. To use it:

1. Install and run the MCP Inspector:
   npx @modelcontextprotocol/inspector
2. Access the Inspector at http://localhost:5173
3. Configure the connection in the Inspector UI:
   • Transport Type: STDIO
   • Command: thingspanel-mcp
   • Arguments: (leave empty or add options if needed)
4. Click "Connect" to start testing your MCP server

Alternatively, launch the Inspector with your command directly:

Troubleshooting

"Not Found" on localhost:8000

If you see a "Not Found" error when accessing http://localhost:8000, this is normal. The MCP server is not designed to be accessed directly through a web browser. It communicates using specific protocols for AI models.

Port conflicts with MCP Inspector

If you encounter a port conflict error like Error: listen EADDRINUSE: address already in use :::3000:

1. Use a different port:
   npx @modelcontextprotocol/inspector --port 3001 -- $(which thingspanel-mcp)
2. Find and terminate the process using port 3000:
   lsof -i :3000 # On macOS/Linux kill [PID] # Kill the process by its ID

Connection errors in MCP Inspector

If you encounter connection errors when trying to connect to your MCP server from the Inspector:

1. Ensure your ThingsPanel MCP server isn't already running in another terminal
2. Check that the command and arguments are correct
3. Make sure all required environment variables are set
4. Try using the full path to Python:
   npx @modelcontextprotocol/inspector -- $(which python) -m thingspanel_mcp

Development

1. Clone the repository
2. Install development dependencies: pip install -e ".[dev,lint]"
3. Run tests: pytest

Using Makefile

The project includes a Makefile to simplify common tasks:

License

Apache License 2.0