UltronSysController/ultron-mcp-server

UltronCloud MCP Server

🌟 Why UltronCloud Personal Edition?

Build powerful IoT applications in minutes, not months. UltronCloud Personal Edition provides enterprise-grade smart home APIs that work seamlessly with modern AI assistants and traditional applications.

✨ Key Features

• 🔐 34 Secure APIs - Production-ready, thoroughly tested endpoints
• 🤖 AI-Native Design - Built for ChatGPT, Claude, LangChain integration
• ⚡ Real-time Control - Instant device management and status updates
• 📊 Advanced Analytics - Energy monitoring, sensor data, historical insights
• 🎭 Scene Management - Create and execute complex automation scenarios
• 🔔 Smart Alerts - Intelligent notifications and anomaly detection
• 🌐 Multi-Protocol - REST API, MCP Server, OpenAPI 3.0 specification
• 🚀 Developer-Friendly - Comprehensive docs, examples, and SDKs

🚀 Quick Start

Prerequisites

• Node.js 18+
• UltronCloud Developer Account
• Credentials from UltronCloud Account

Installation & Setup

# 1. Clone the repository
git clone https://github.com/UltronSysController/ultron-user-mcp-server.git
cd ultron-user-mcp-server

# 2. Install dependencies
npm install

# 3. For Claude CLI/Code users - Global installation
npm link  # Creates global command 'ultron-mcp'

# 4. Run interactive setup (Recommended)
npm run setup
# This will:
# - Ask for your App ID and API Key
# - Fetch your available groups
# - Help you select the right group
# - Test the connection
# - Save everything to .env

# 4. Test your setup
npm test

# 5. Start using
npm start  # Run MCP server

Manual Setup (Alternative)

# If you prefer manual configuration
cp .env.example .env
# Edit .env with:
# - ULTRON_APP_ID=your-app-id
# - ULTRON_API_KEY=your-api-key  
# - ULTRON_GROUP_ID=your-group-id (optional)

💻 Usage Examples

JavaScript/Node.js

import axios from 'axios';

// Configure API client
const ultronAPI = axios.create({
  baseURL: 'https://api.ultroncloud.com',
  headers: {
    'Authorization': `Bearer ${process.env.ULTRON_API_KEY}`,
    'X-App-Id': process.env.ULTRON_APP_ID
  }
});

// Get all devices
const devices = await ultronAPI.post('/usr/v4/GetGroupDevices', {
  groupId: 'grp_123456'
});

// Control a device
const result = await ultronAPI.post('/usr/v4/SendCommand', {
  sn: 'UT3702A0002201234',
  iotDevs: ['Switch'],
  cmd: 'toggle'
});

Python

import requests

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'X-App-Id': APP_ID
}

# Control device
response = requests.post(
    'https://api.ultroncloud.com/usr/v4/SendCommand',
    headers=headers,
    json={'sn': 'device_id', 'iotDevs': ['Switch'], 'cmd': 'on'}
)

🤖 AI Agent Integration

Claude Desktop & CLI

# For Claude Desktop & CLI - Full local control
npm start

# Works with both:
# - Claude Desktop app (macOS/Windows)
# - Claude CLI for terminal/automation
# See CLAUDE_CLI_GUIDE.md for detailed setup

ChatGPT GPTs

1. Open GPT Builder
2. Import ultroncloud-api-personal.yaml
3. Configure authentication with Bearer token and X-App-Id header

Claude Configuration

// Add to claude_desktop_config.json or .claude/config.json
{
  "mcpServers": {
    "ultroncloud": {
      "command": "node",
      "args": ["path/to/ultron-mcp-server.js"],
      "env": {
        "ULTRON_APP_ID": "your-app-id",
        "ULTRON_API_KEY": "your-api-key"
      }
    }
  }
}

LangChain

from langchain.tools import Tool
from langchain.utilities import Requests

requests = Requests(headers={
    'Authorization': f'Bearer {API_KEY}',
    'X-App-Id': APP_ID
})

📊 API Overview

Available API Categories

📦 Project Structure

ultroncloud-api-personal/
├── ultroncloud-api-personal.yaml  # OpenAPI 3.0 specification
├── ultron-mcp-server.js          # MCP server for Claude
├── package.json                  # Node.js package config
├── .env.example                  # Environment template
├── DEVELOPER_GUIDE.md            # Complete developer guide
├── README.md                     # This file
└── examples/                     # Code examples
    ├── javascript/               # JS/Node.js examples
    ├── python/                   # Python examples
    └── postman/                  # Postman collection

🎆 Common Use Cases

Smart Home Dashboard

// Get all devices with real-time status
const dashboard = await Promise.all([
  ultronAPI.post('/usr/v4/GetGroupDevices', { groupId }),
  ultronAPI.post('/usr/v4/GetGroupDeviceStates', { groupId })
]);

Energy Management

// Monitor power consumption
const powerData = await ultronAPI.post('/usr/v4/GetDeviceRealTimeKWh', {
  sn: 'device_serial'
});

Automation Rules

// Create temperature-based automation
const rule = await ultronAPI.post('/usr/v4/CreateSensorRangePolicy', {
  groupId, name: 'Auto AC',
  sensorType: 'temperature',
  range: { min: 20, max: 28 },
  actions: [{ type: 'device_control', config: {...} }]
});

🔒 Security & Best Practices

Security Features

• ✅ All high-risk operations removed
• ✅ Role-based access control
• ✅ Rate limiting protection
• ✅ Secure authentication with App ID + API Key

Best Practices

1. Never expose credentials in client-side code
2. Use environment variables for sensitive data
3. Implement server-side proxy for web applications
4. Rotate API keys regularly
5. Monitor API usage in developer dashboard

📚 Documentation

• - Complete integration guide
• - Claude Desktop & CLI setup
• - OpenAPI specification
• - Get started in 5 minutes
• - Code samples in multiple languages

🎯 Roadmap

• TypeScript SDK
• Python SDK
• Webhook support
• WebSocket real-time updates
• GraphQL API
• More AI platform integrations

🤝 Contributing

We welcome contributions! Please see our for details.

📧 Support

• GitHub Issues: Report bugs or request features
• Developer Forum: Join the community
• Email: developer@ultroncloud.com
• Discord: UltronCloud Developers

📄 License

MIT License - see file for details.

🌟 Acknowledgments

Built with ❤️ by the UltronCloud team for the global developer community.