# 🎮 Nordic Thingy:52 MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](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.

![Nordic Thingy](https://nordicsemi.com/-/media/Images/Products/DevKits/nRF52-Series/Nordic-Thingy52/Nordic-Thingy-52-front.png?sc_lang=en)

---

## ✨ 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)