Manusevl/mcp-mqtt-plc

MCP MQTT PLC Server

A Model Context Protocol (MCP) server that enables AI assistants to discover and monitor industrial PLCs through MQTT communication. Perfect for industrial automation monitoring, IoT data analysis, and SCADA systems integration.

🚀 Quick Installation

npm install -g mcp-mqtt-plc

✨ Features

• 🔍 Topic Discovery: Automatically discovers all available MQTT topics
• 📊 Detailed Data Retrieval: Get comprehensive information about specific topics
• 🤖 AI Integration: Native support for VS Code MCP and Claude Desktop
• ⚡ Auto-start: Server starts automatically when needed - no background processes
• 🔧 Configurable: Easy environment-based configuration
• 🛡️ Secure: Support for authenticated MQTT connections
• 🔒 Read-Only: Safe monitoring interface with no control commands

📋 Available Tools

1. search_mqtt_topics - Discover and list all available MQTT topics

   • Returns overview of all topics with message counts and sample data
   • No parameters required
   • Use this first to understand what data is available

2. get_topic_details - Get detailed information about specific topics

   • Requires topicPattern parameter (exact name or partial match)
   • Returns full data payload and metadata
   • Supports pattern matching for flexible topic discovery

🛠️ Setup

For VS Code (Native MCP)

1. Install globally:

   npm install -g mcp-mqtt-plc
   

2. Add to VS Code settings.json:

{ "servers": { "mcp-mqtt-plc": { "command": "mcp-mqtt-plc", "args": [], "env": { "MQTT_BROKER_URL": "yourMQTTURL", "MQTT_CLIENT_ID": "vscode-mcp-client", "MQTT_USERNAME": "youruser", "MQTT_PASSWORD": "yourpassword", } } } }

### For Claude Desktop

1. **Install globally:**
```bash
npm install -g mcp-mqtt-plc

2. Configure Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json):

{ "mcpServers": { "mcp-mqtt-plc": { "command": "mcp-mqtt-plc", "args": [], "env": { "MQTT_BROKER_URL": "yourURL", "MQTT_CLIENT_ID": "vscode-mcp-client", "MQTT_USERNAME": "youruser", "MQTT_PASSWORD": "yourpassword" } } } }

## ⚙️ Configuration

Configure via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `MQTT_BROKER_URL` | `mqtt://localhost:1883` | MQTT broker connection URL |
| `MQTT_CLIENT_ID` | `mcp-plc-server` | MQTT client identifier |
| `MQTT_USERNAME` | - | MQTT username (optional) |
| `MQTT_PASSWORD` | - | MQTT password (optional) |
| `MQTT_PLC_DATA_TOPIC` | `plc/data` | Default PLC data topic |
| `MQTT_PLC_COMMANDS_TOPIC` | `plc/commands` | Default PLC command topic |

## 🎯 Usage Examples

### Discovery Workflow

User: "What industrial data is available?" → AI calls search_mqtt_topics() → Shows: "factory/temperature", "plc/motors", "sensors/pressure"

User: "What's the current temperature?"
→ AI calls get_topic_details("temperature") → Returns: {"temperature": 72.5, "unit": "°F", "timestamp": "..."}

### Pattern Matching

get_topic_details("motor") # Finds topics containing "motor" get_topic_details("plc/data") # Exact topic match get_topic_details("temp") # Finds temperature-related topics

## 🧪 Development & Testing

### NPM Scripts
- `npm run build` - Build TypeScript to JavaScript  
- `npm run start` - Start the MCP server
- `npm run dev` - Build and start in one command
- `npm run watch` - Build in watch mode
- `npm run test-mqtt` - Test MQTT connection
- `npm run mock-plc` - Start mock PLC for testing

### Local Development
1. Clone the repository
2. Install dependencies: `npm install`
3. Create `.env` file with your MQTT configuration
4. Build: `npm run build`
5. Test: `npm run test-mqtt`

### Testing with Mock PLC
```bash
# Terminal 1: Start mock PLC
npm run mock-plc

# Terminal 2: Test the server
npm run test-mqtt

🏭 Industrial Use Cases

• Factory Monitoring: Real-time production data analysis
• SCADA Integration: Connect AI assistants to existing SCADA systems
• Predictive Maintenance: AI analysis of sensor data trends
• Quality Control: Automated monitoring of production parameters
• Energy Management: Smart analysis of power consumption data
• Safety Monitoring: Real-time alert analysis and response

🛡️ Security & Safety

• Read-Only Interface: No control commands - monitoring only
• Secure Connections: Support for authenticated MQTT brokers
• No Data Storage: Real-time monitoring without data persistence
• Isolated Execution: Runs in controlled MCP environment

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make changes and add tests
4. Build and test: npm run build && npm run test-mqtt
5. Commit: git commit -am 'Add feature'
6. Push: git push origin feature-name
7. Create Pull Request

📄 License

MIT License - see file for details.

Perfect for safe, intelligent monitoring of industrial MQTT data with AI assistants! 🏭🤖