Meshtastic MCP Server

# Changelog ## Version 2.0.1 - Multi-Client Support Documentation ### New Documentation ✨ **CLIENTS.md - Comprehensive Multi-Client Configuration Guide** - Complete setup instructions for multiple MCP clients - Detailed configuration for Windsurf IDE - Detailed configuration for Cursor IDE - ChatGPT Desktop setup and notes - Generic MCP client configuration - MCP Inspector testing guide - Troubleshooting for each client - IDE-specific features and workflows - Security considerations - Advanced configuration examples ### Supported Clients | Client | Documentation | Status | |--------|--------------|--------| | **Claude Desktop** | ✅ Full guide | Official support | | **Windsurf IDE** | ✅ Full guide | Community support | | **Cursor IDE** | ✅ Full guide | Community support | | **ChatGPT Desktop** | ✅ Full guide | Experimental | | **Generic MCP** | ✅ Full guide | Universal | ### Documentation Updates #### README.md - Added "Other Clients" section - Links to CLIENTS.md for non-Claude setups - Updated project structure - Enhanced resources section ### Benefits - **Broader ecosystem support** - Use Meshtastic MCP in your preferred IDE - **Better developer experience** - IDE-specific tips and workflows - **Easier troubleshooting** - Client-specific debugging guides - **Future-proof** - Generic configuration for new MCP clients ### Example Use Cases **Windsurf**: Monitor your mesh network while coding with Cascade AI proactively checking for messages **Cursor**: Use Composer to orchestrate complex mesh operations across multiple nodes **ChatGPT**: Quick mesh queries from the desktop app --- ## Version 2.0.0 - Enhanced Features Release ### Major New Features ✨ **Alert Messages** - New `send_alert` tool for high-priority emergency messages - Generates special notifications on receiving devices - Perfect for urgent communications ✨ **Network Traceroute** - New `send_traceroute` tool to discover routes to nodes - New `get_traceroute_results` tool to view path and SNR data - Supports configurable hop limits (default 7) - Shows SNR in both directions for each hop - Essential for network topology analysis ✨ **Comprehensive Telemetry** - New `send_telemetry_request` tool for device monitoring - New `get_telemetry_results` tool to retrieve telemetry data - Supports multiple telemetry types: - device_metrics (battery, voltage, channel utilization) - environment_metrics (temperature, humidity, pressure) - power_metrics (battery status, charging info) - air_quality_metrics (PM2.5, PM10, etc.) - Broadcast or targeted telemetry requests ✨ **Position Sharing** - New `send_position` tool to share GPS coordinates - Supports latitude, longitude, and altitude - Broadcast or send to specific nodes ✨ **Waypoint Management** - New `send_waypoint` tool to create points of interest - Features: - Custom names and descriptions - Icon selection (0-63) - Expiration times - Optional waypoint IDs - New `delete_waypoint` tool to remove waypoints ✨ **Enhanced Device Management** - New `get_device_metadata` tool - firmware version, hardware model, capabilities - New `set_owner` tool - set device name and ham radio license status - New `reboot_node` tool - remotely reboot with configurable delay - New `shutdown_node` tool - remotely shutdown with configurable delay ✨ **Improved Network Info** - New `show_network_info` tool for formatted, human-readable network status - Enhanced node information display ### Updated Components #### server2.py (NEW) - Complete enhanced implementation with 25 tools (up from 9) - Added comprehensive callbacks for traceroute and telemetry - Global state management for traceroute and telemetry results - Improved error handling and logging - Support for advanced Meshtastic features ### New Capabilities Summary | Category | v0.2.0 | v2.0.0 | Added | |----------|--------|--------|-------| | **Connection Tools** | 2 | 2 | 0 | | **Messaging Tools** | 2 | 3 | +1 (alerts) | | **Network Discovery** | 4 | 4 | 0 | | **Traceroute** | 0 | 2 | +2 (new) | | **Telemetry** | 0 | 2 | +2 (new) | | **Position** | 1 | 1 | 0 | | **Waypoints** | 0 | 2 | +2 (new) | | **Device Management** | 1 | 5 | +4 | | **Total Tools** | 9 | 25 | +16 | ### Documentation Updates #### README.md - Added all new features to feature list - Updated usage examples for new tools - Comprehensive tool listing with categories - Updated project structure #### EXAMPLES.md - Added traceroute examples - Added telemetry request examples - Added waypoint management examples - Added device management examples - Updated advanced use cases - Added new pro tips #### QUICKSTART.md - Updated to reference server2.py - Added examples of new features ### Usage Examples **Traceroute:** ``` "Send a traceroute to node !a1b2c3d4" "Show me the traceroute results" ``` **Telemetry:** ``` "Request device telemetry from all nodes" "Request environment metrics from the base station" "Show me the telemetry data" ``` **Waypoints:** ``` "Create a waypoint called 'Camp Alpha' at 37.7749, -122.4194" "Delete waypoint ID 12345" ``` **Device Management:** ``` "What's my device metadata?" "Set my device owner to 'John Doe' with short name 'JD'" "Reboot my device in 30 seconds" ``` ### Technical Details - Uses Meshtastic Python library callbacks for async data collection - Traceroute results stored globally with timestamps - Telemetry data indexed by node ID - SNR data captured in both directions for traceroute - Support for all Meshtastic telemetry types ### Breaking Changes None - this is backward compatible with v0.2.0 ### Migration Guide If updating from v0.2.0: 1. No changes required to existing usage 2. New tools are additive 3. Replace `server.py` with `server2.py` in your Claude config 4. All existing functionality works as before ### Known Limitations 1. **Traceroute**: Results arrive asynchronously, may need to wait 10-30 seconds 2. **Telemetry**: Not all devices support all telemetry types 3. **Waypoints**: Icon support depends on client application 4. **Device management**: Reboot/shutdown affects the connected device --- ## Version 0.2.0 - Bluetooth Support ### New Features ✨ **Bluetooth Low Energy (BLE) Support** - Connect to Meshtastic devices wirelessly via Bluetooth - No USB cables required - Works within ~10-30 meter range ✨ **Device Discovery** - New `scan_bluetooth` tool to find nearby Meshtastic devices - Automatically filters for Meshtastic nodes - Shows device name, MAC address, and signal strength (RSSI) ### Updated Components #### server.py - Added `meshtastic.ble_interface` import - Updated `get_interface()` to support "bluetooth" and "ble" connection types - Added new `scan_bluetooth` tool to tool list - Implemented Bluetooth scanning with `bleak` library - Updated `connect` tool to accept Bluetooth as connection option #### test_connection.py - Added `test_bluetooth()` function for testing BLE connections - Added `scan_bluetooth()` async function for device discovery - Updated CLI to support `--type bluetooth` and `--type scan` - Added timeout parameter for Bluetooth scans #### requirements.txt - Added `bleak>=0.21.0` for Bluetooth Low Energy support ### New Documentation #### BLUETOOTH.md (NEW) Comprehensive guide covering: - Why use Bluetooth - Prerequisites and setup - Finding devices with scanning - Platform-specific instructions (macOS, Linux, Windows) - Detailed troubleshooting - Security considerations - Comparison table: Bluetooth vs Serial vs TCP #### Updated Existing Docs - **README.md**: Added Bluetooth to features, usage examples, and tool list - **QUICKSTART.md**: Added Bluetooth testing and troubleshooting - **EXAMPLES.md**: Added Bluetooth connection examples ### Usage Examples **Scan for devices:** ```bash python test_connection.py --type scan ``` **Connect via Bluetooth:** ```bash python test_connection.py --type bluetooth --device AA:BB:CC:DD:EE:FF ``` **With Claude:** ``` "Scan for nearby Meshtastic devices via Bluetooth" "Connect to my Meshtastic device via Bluetooth at AA:BB:CC:DD:EE:FF" ``` ### Technical Details - Uses `bleak` library for cross-platform BLE support - Async scanning with configurable timeout (default 10 seconds) - Filters devices by name matching "meshtastic" or "mesh" - Supports standard Meshtastic BLE interface - MAC address format agnostic (handles different OS formats) ### Platform Support | Platform | Status | Notes | |----------|--------|-------| | Linux | ✅ Full | Requires `bluez` | | macOS | ✅ Full | Works out of box | | Windows | ✅ Full | Windows 10+ recommended | ### Known Limitations 1. **Single connection**: Only one BLE client can connect at a time 2. **Range**: Limited to Bluetooth range (~10-30m) 3. **Battery**: BLE uses more power than sleep mode 4. **Pairing**: Some platforms require device pairing first ### Breaking Changes None - this is a backward-compatible addition. ### Dependencies New dependency added: ``` bleak>=0.21.0 ``` ### Migration Guide If updating from v0.1.0: 1. Update dependencies: ```bash pip install -r requirements.txt ``` 2. Existing serial and TCP connections work exactly as before 3. New Bluetooth functionality is opt-in ### Future Enhancements Potential additions for future versions: - Auto-reconnect on connection drop - Connection persistence/remembered devices - Multi-device support (switching between devices) - BLE signal strength monitoring - Automatic device selection based on signal strength --- ## Version 0.1.0 - Initial Release ### Features - Serial (USB) connection support - TCP/IP connection support - Send/receive messages - Node management - Position sharing - Channel listing - Basic MCP server implementation