Nordic Thingy:52 MCP Server

# 🎮 Nordic Thingy:52 MCP Server [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://docs.anthropic.com/mcp) **Control your Nordic Thingy:52 IoT device directly from Claude Desktop using the Model Context Protocol (MCP)** Transform your Claude Desktop into an IoT control center! This MCP server enables Claude to discover, connect to, and control Nordic Thingy:52 devices via Bluetooth LE - all through natural language conversation.  --- ## ✨ Features - 🔍 **Auto-Discovery**: Scan for nearby Thingy devices - 🔌 **Easy Connection**: Connect via Bluetooth LE with a single command - 💡 **LED Control**: Set RGB colors, create lighting effects - 🔊 **Sound Control**: Play built-in sounds and tones - 📊 **Sensor Reading**: Monitor temperature, humidity, pressure, CO2, and TVOC - 🤖 **AI Integration**: Control everything through natural Claude conversations - 🔄 **Real-time Updates**: Instant feedback and status monitoring --- ## 📋 Prerequisites ### Hardware - **Nordic Thingy:52** device ([Purchase here](https://www.nordicsemi.com/Products/Development-hardware/Nordic-Thingy-52)) - Computer with **Bluetooth LE** support - Battery or USB power for Thingy ### Software - **Python 3.10 or higher** - **Claude Desktop** app ([Download here](https://claude.ai/download)) - **macOS** (tested) or **Linux** with BlueZ (Windows support via bleak) --- ## 🚀 Quick Start ### 1. Installation ```bash # Clone the repository git clone https://github.com/yourusername/mcp-server-nordic-thingy.git cd mcp-server-nordic-thingy # Create virtual environment python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install dependencies pip install -r requirements.txt ``` ### 2. Configure Claude Desktop Add the server to your Claude Desktop configuration: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "nordic-thingy": { "command": "python3", "args": ["/absolute/path/to/mcp_server_nordic_thingy.py"] } } } ``` ### 3. Restart Claude Desktop Close and reopen Claude Desktop to load the server. ### 4. Start Using! Try these prompts in Claude: ``` "Find my Nordic Thingy and connect to it" "Turn the Thingy LED red" "Check the temperature and air quality" "Play a beep sound" ``` --- ## 📖 Documentation ### Available Tools | Tool | Description | Example Prompt | |------|-------------|----------------| | `thingy_scan` | Discover nearby devices | "Scan for Thingy devices" | | `thingy_connect` | Connect to a device | "Connect to XX:XX:XX:XX:XX:XX" | | `thingy_disconnect` | Disconnect device | "Disconnect from Thingy" | | `thingy_set_led` | Set RGB LED color | "Set LED to red" | | `thingy_led_off` | Turn off LED | "Turn off the LED" | | `thingy_play_sound` | Play sound (1-8) | "Play sound 3" | | `thingy_beep` | Quick beep | "Make it beep" | | `thingy_get_sensors` | Read all sensors | "Check all sensors" | | `thingy_get_status` | Connection status | "Is Thingy connected?" | ### Sensor Data The Thingy:52 provides: - 🌡️ **Temperature** (°C) - 💧 **Humidity** (%) - 🔽 **Pressure** (hPa) - 🌫️ **CO2** (ppm) - Air quality - 🌬️ **TVOC** (ppb) - Volatile organic compounds - 🎨 **Color** sensor (RGB + Clear) --- ## 🎯 Example Use Cases ### 1. Home Office Monitor ``` "Monitor my office air quality. Check CO2 every 5 minutes and alert me if it's unhealthy (>1000 ppm)" ``` ### 2. Smart Notifications ``` "When you detect motion (temperature change), flash the LED blue and beep twice" ``` ### 3. Temperature Alerts ``` "If the temperature goes above 25°C, set the LED to red and play sound 5" ``` ### 4. Mood Lighting ``` "Create a relaxing atmosphere: set the LED to a calm blue color" ``` ### 5. Meeting Room Status ``` "Create a meeting room indicator: - Green LED: Good air quality, room available - Yellow LED: Moderate air quality - Red LED: Poor air quality, needs ventilation" ``` **More examples in [PROMPT_GUIDE.md](./PROMPT_GUIDE.md)** --- ## 🛠️ Development ### Project Structure ``` mcp-server-nordic-thingy/ ├── mcp_server_nordic_thingy.py # Main MCP server ├── requirements.txt # Python dependencies ├── README.md # This file ├── PROMPT_GUIDE.md # Comprehensive prompt examples ├── CONTRIBUTING.md # Contribution guidelines ├── LICENSE # MIT License ├── examples/ # Example scripts │ ├── basic_control.py │ ├── sensor_monitor.py │ └── automation.py └── docs/ # Additional documentation ├── API.md # API reference ├── TROUBLESHOOTING.md # Common issues └── HARDWARE.md # Hardware details ``` ### Running Tests ```bash # Install dev dependencies pip install -r requirements-dev.txt # Run tests pytest tests/ # Run with coverage pytest --cov=. tests/ ``` ### Local Testing Test the MCP server without Claude: ```bash # Run server in test mode python3 mcp_server_nordic_thingy.py --test # Or use the test client python3 examples/test_client.py ``` --- ## 🤝 Contributing We welcome contributions! Here's how you can help: ### Ways to Contribute - 🐛 Report bugs - 💡 Suggest features - 📝 Improve documentation - 🎯 Share useful prompts - 🔧 Submit pull requests - ⭐ Star the repo! ### Getting Started 1. **Fork** the repository 2. **Create** a feature branch (`git checkout -b feature/AmazingFeature`) 3. **Commit** your changes (`git commit -m 'Add AmazingFeature'`) 4. **Push** to the branch (`git push origin feature/AmazingFeature`) 5. **Open** a Pull Request See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines. ### Share Your Prompts! Found a great way to use the Thingy? Share your prompts in [PROMPT_GUIDE.md](./PROMPT_GUIDE.md)! --- ## 🐛 Troubleshooting ### Thingy Not Found 1. **Check Power**: Ensure Thingy is powered on (blue LED should pulse) 2. **Bluetooth**: Enable Bluetooth on your computer 3. **Distance**: Keep Thingy within 10 meters 4. **Interference**: Move away from other Bluetooth devices 5. **Reset**: Hold Thingy button for 5 seconds to reset ### Connection Failed ```bash # Check Bluetooth status hcitool dev # Linux system_profiler SPBluetoothDataType # macOS # Scan manually hcitool lescan # Linux # Reset Bluetooth (macOS) sudo pkill bluetoothd ``` ### Claude Can't Find Server 1. Check `claude_desktop_config.json` path is correct 2. Verify Python path: `which python3` 3. Check server logs in Claude Desktop Developer Tools 4. Restart Claude Desktop **More troubleshooting in [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md)** --- ## 📚 Resources ### Nordic Thingy:52 - [Product Page](https://www.nordicsemi.com/Products/Development-hardware/Nordic-Thingy-52) - [User Guide](https://infocenter.nordicsemi.com/topic/ug_thingy52/UG/thingy52/intro/frontpage.html) - [Firmware](https://github.com/NordicSemiconductor/Nordic-Thingy52-FW) ### MCP (Model Context Protocol) - [MCP Documentation](https://docs.anthropic.com/mcp) - [MCP GitHub](https://github.com/anthropics/mcp) - [MCP Server Examples](https://github.com/anthropics/mcp-servers) ### Claude Desktop - [Download Claude](https://claude.ai/download) - [Claude Documentation](https://docs.anthropic.com/) --- ## 🎓 Learning Path ### Beginners 1. Read [Quick Start](#-quick-start) 2. Try [basic prompts](./PROMPT_GUIDE.md#quick-start-prompts) 3. Explore [sensor reading](./PROMPT_GUIDE.md#-sensor-reading) ### Intermediate 1. Create [conditional automations](./PROMPT_GUIDE.md#conditional-actions) 2. Build [sequences](./PROMPT_GUIDE.md#scripted-sequences) 3. Monitor [air quality](./PROMPT_GUIDE.md#air-quality-alerts) ### Advanced 1. Multi-device control 2. Database integration 3. Web dashboard 4. Custom tool development --- ## 🌟 Showcase ### Community Projects **Smart Plant Monitor** by @username > Automated plant care using humidity and temperature sensors **Home Lab Monitor** by @username > Server room monitoring with multiple Thingys **Meeting Room Assistant** by @username > Intelligent meeting room status indicator *Add your project! Submit a PR to appear here.* --- ## 📊 Stats - 🌡️ 6 environmental sensors - 💡 16.7 million LED colors - 🔊 8 built-in sounds - ⚡ 30-day battery life - 📡 10m Bluetooth range - 🔋 240 mAh Li-Po battery --- ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ``` MIT License Copyright (c) 2025 Nordic Thingy MCP Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software")... ``` --- ## 🙏 Acknowledgments - **Anthropic** for Claude and MCP - **Nordic Semiconductor** for the amazing Thingy:52 hardware - **Bleak** library maintainers for excellent Bluetooth LE support - All **contributors** who make this project better --- ## 📞 Support - 💬 **GitHub Issues**: [Report bugs or request features](https://github.com/yourusername/mcp-server-nordic-thingy/issues) - 📧 **Email**: your-email@example.com - 🐦 **Twitter**: @yourhandle - 💬 **Discord**: [Join our community](#) (if available) --- ## 🗺️ Roadmap ### v1.0 (Current) - ✅ Basic Bluetooth LE connection - ✅ LED control - ✅ Sound playback - ✅ Sensor reading - ✅ MCP integration ### v1.1 (Planned) - 🔄 Continuous sensor monitoring - 📊 Data logging - 🌐 Web dashboard - 🔔 Smart alerts - 🎨 Advanced LED effects ### v2.0 (Future) - 🤖 ML-based anomaly detection - 🏠 Home Assistant integration - 📱 Mobile app - 🌍 Multi-Thingy coordination - ☁️ Cloud sync **Vote on features in [GitHub Discussions](https://github.com/yourusername/mcp-server-nordic-thingy/discussions)** --- ## 🎉 Getting Started in 60 Seconds ```bash # 1. Clone git clone https://github.com/yourusername/mcp-server-nordic-thingy.git cd mcp-server-nordic-thingy # 2. Install pip install -r requirements.txt # 3. Configure Claude (edit with your path) echo '{ "mcpServers": { "nordic-thingy": { "command": "python3", "args": ["'$(pwd)'/mcp_server_nordic_thingy.py"] } } }' > ~/Library/Application\ Support/Claude/claude_desktop_config.json # 4. Restart Claude Desktop # 5. Try it! # In Claude: "Find my Thingy and turn it red" ``` --- **Built with ❤️ by the Nordic Thingy MCP community** *If you find this useful, please ⭐ star the repository!* [⬆ Back to top](#-nordic-thingy52-mcp-server)