Content
# Meshtastic MCP Server
A Model Context Protocol (MCP) server that enables Claude and other AI assistants to interact with Meshtastic mesh networks for off-grid communication.
## Features
### Connection & Discovery
- 🔌 Connect to Meshtastic devices via Serial (USB), TCP/IP, or Bluetooth
- 🔍 Scan for nearby Bluetooth devices
### Messaging
- 💬 Send and receive text messages on the mesh network
- 🚨 Send high-priority alert messages
- 📥 Retrieve message history
### Network Analysis
- 📡 Query node information and network topology
- 🗺️ Send traceroute requests with SNR data
- 📊 Request and monitor telemetry (device metrics, environment, power, air quality)
- 📶 View formatted network information
### Location & Navigation
- 📍 Share GPS positions
- 📌 Send waypoints (points of interest) with icons and expiration
- 🗑️ Delete waypoints
### Device Management
- 📻 List configured channels
- ⚙️ Get device metadata (firmware, hardware model)
- 👤 Set device owner name and license status
- 🔄 Reboot or shutdown devices
## Installation
### Prerequisites
- Python 3.10 or higher
- A Meshtastic device (connected via USB or network)
- Claude Desktop app or MCP-compatible client
### Setup
1. **Clone or create the project directory:**
```bash
mkdir meshtastic-mcp
cd meshtastic-mcp
```
2. **Install dependencies:**
```bash
pip install -r requirements.txt
```
3. **Make the server executable:**
```bash
chmod +x server2.py
```
## Configuration
This MCP server works with multiple AI assistants and IDEs. Choose your preferred client:
### Quick Setup - Claude Desktop
Add the following to your Claude Desktop configuration file:
**MacOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"meshtastic": {
"command": "python",
"args": ["/absolute/path/to/meshtastic-mcp/server2.py"]
}
}
}
```
Replace `/absolute/path/to/meshtastic-mcp/` with the actual path to your installation.
### Other Clients
**See [CLIENTS.md](CLIENTS.md) for detailed configuration instructions for:**
- 🌊 **Windsurf IDE** - AI-powered development environment
- 📝 **Cursor IDE** - AI-first code editor
- 💬 **ChatGPT Desktop** - OpenAI's desktop app
- 🔧 **Generic MCP clients** - Any MCP-compatible tool
Each client has specific configuration paths and setup steps detailed in the guide.
## Usage
Once configured, you can use natural language with Claude to interact with your Meshtastic device:
### Connect to Device
```
"Connect to my Meshtastic device via serial"
"Connect to my Meshtastic device at 192.168.1.100 via TCP"
"Scan for nearby Meshtastic devices via Bluetooth"
"Connect to my Meshtastic device via Bluetooth at AA:BB:CC:DD:EE:FF"
```
### Send Messages
```
"Send a message 'Hello mesh network!' to all nodes"
"Send 'Meeting at 3pm' to node !a1b2c3d4"
"Send an alert: 'Emergency assistance needed at trailhead'"
```
### Network Discovery & Analysis
```
"Show me all nodes in the mesh"
"Get information about node !a1b2c3d4"
"Send a traceroute to node !a1b2c3d4"
"Show me the traceroute results"
"Request telemetry from all nodes"
"What's the device metadata?"
```
### Location & Waypoints
```
"Send my position at latitude 37.7749, longitude -122.4194"
"Create a waypoint called 'Campsite Alpha' at 37.7749, -122.4194"
"Delete waypoint ID 12345"
```
### Device Management
```
"What channels are configured on my device?"
"Set my device owner to 'John Doe' with short name 'JD'"
"Reboot my device"
"Show formatted network information"
```
### Read Messages
```
"Show me the last 10 messages"
"What messages have I received?"
```
## Available Tools
The MCP server exposes the following tools:
### Connection
- `connect` - Connect to a Meshtastic device (serial/TCP/Bluetooth)
- `scan_bluetooth` - Scan for nearby Meshtastic devices via Bluetooth
### Messaging
- `send_message` - Send text messages to nodes or channels
- `send_alert` - Send high-priority alert messages
- `get_messages` - Retrieve recent received messages
### Network Discovery
- `get_nodes` - List all nodes in the mesh network
- `get_node_info` - Get detailed info about a specific node
- `get_local_node` - Get info about the connected device
- `show_network_info` - Get formatted network information
### Traceroute
- `send_traceroute` - Send traceroute request to discover path and SNR
- `get_traceroute_results` - Retrieve traceroute results
### Telemetry
- `send_telemetry_request` - Request device/environment/power/air quality metrics
- `get_telemetry_results` - Retrieve telemetry data
### Location
- `send_position` - Broadcast GPS coordinates
### Waypoints
- `send_waypoint` - Create a waypoint (point of interest)
- `delete_waypoint` - Delete a waypoint
### Device Management
- `get_channels` - List configured channels
- `get_device_metadata` - Get hardware and firmware information
- `set_owner` - Set device owner name and license status
- `reboot_node` - Reboot the device
- `shutdown_node` - Shutdown the device
## Troubleshooting
### Serial Connection Issues
If you have permission issues accessing serial devices:
**Linux:**
```bash
sudo usermod -a -G dialout $USER
# Then log out and back in
```
**MacOS:**
No special permissions needed typically, but ensure the device appears in `/dev/tty.*`
### Finding Your Device
**Serial (USB):**
- Linux: Usually `/dev/ttyUSB0` or `/dev/ttyACM0`
- MacOS: Usually `/dev/tty.usbserial-*`
- Windows: Usually `COM3`, `COM4`, etc.
**TCP/IP:**
- Check your device's WiFi settings in the Meshtastic app
- Default hostname is often `meshtastic.local`
- Or use the IP address directly
**Bluetooth:**
- Use the scan feature: `python test_connection.py --type scan`
- Note the MAC address (e.g., `AA:BB:CC:DD:EE:FF`)
- See BLUETOOTH.md for detailed Bluetooth setup guide
### Message History
The server maintains a message history in memory. This resets when the server restarts. For persistent storage, consider extending the server to save messages to a database.
## Development
### Project Structure
```
meshtastic-mcp/
├── server2.py # Enhanced MCP server implementation
├── requirements.txt # Python dependencies
├── README.md # This file
├── CLIENTS.md # Multi-client configuration guide
├── EXAMPLES.md # Usage examples
├── QUICKSTART.md # Quick start guide
├── CHANGELOG.md # Version history
└── BLUETOOTH.md # Bluetooth setup guide
```
### Extending the Server
To add new tools:
1. Add a new `Tool` definition in `list_tools()`
2. Add the corresponding handler in `call_tool()`
3. Use the `meshtastic` Python library for device interaction
### Example: Adding a Custom Tool
```python
Tool(
name="my_custom_tool",
description="Description of what it does",
inputSchema={
"type": "object",
"properties": {
"param": {
"type": "string",
"description": "Parameter description"
}
},
"required": ["param"]
}
)
```
## Security Considerations
- The server has full access to your Meshtastic device
- Messages are sent over LoRa radio and can be received by anyone in range
- Consider encryption settings in your Meshtastic configuration
- Be cautious about sharing sensitive information over the mesh
## License
MIT License - Feel free to use and modify as needed.
## Resources
- [Meshtastic Documentation](https://meshtastic.org/)
- [MCP Documentation](https://modelcontextprotocol.io/)
- [Meshtastic Python Library](https://github.com/meshtastic/python)
- [Client Configuration Guide](CLIENTS.md) - Setup for Windsurf, Cursor, ChatGPT, and more
- [Bluetooth Setup Guide](BLUETOOTH.md) - Detailed guide for BLE connections
## Contributing
Contributions welcome! Some ideas for enhancements:
- Implement message persistence (database storage)
- Add file transfer capabilities
- Support for admin messages and remote configuration
- Group/DM channel creation
- Statistics and analytics dashboards
- Automated network health monitoring
- Multi-device support
## Support
For issues related to:
- **Meshtastic device/firmware**: See [Meshtastic Discord](https://discord.gg/meshtastic)
- **MCP protocol**: See [MCP Documentation](https://modelcontextprotocol.io/)
- **This server**: Open an issue in the repository
