Meshtastic MCP Server

# Meshtastic MCP Usage Examples This document provides example conversations showing how to interact with your Meshtastic device through Claude using the MCP server. ## Initial Setup ### Connect to Your Device **Via Serial (USB):** ``` You: Connect to my Meshtastic device via serial Claude: I'll connect to your Meshtastic device via serial. ✓ Successfully connected to Meshtastic device via serial ``` **Via TCP/IP:** ``` You: Connect to my Meshtastic device at 192.168.1.100 via TCP Claude: Connecting to your Meshtastic device over the network... ✓ Successfully connected to Meshtastic device via tcp ``` **Via Bluetooth:** ``` You: Scan for Meshtastic devices via Bluetooth Claude: I'll scan for nearby Meshtastic devices... Found 2 Meshtastic device(s): [ { "name": "Meshtastic_a1b2", "address": "AA:BB:CC:DD:EE:FF", "rssi": -65 } ] You: Connect to the first one Claude: Connecting via Bluetooth to AA:BB:CC:DD:EE:FF... ✓ Successfully connected to Meshtastic device via bluetooth ``` **Troubleshooting Connection:** ``` You: I'm having trouble connecting. Can you help? Claude: Let me help you troubleshoot. First, let me try to connect... [error details] Here are some things to check: 1. Is your device plugged in via USB? 2. On Linux, the device is usually /dev/ttyUSB0 or /dev/ttyACM0 3. On MacOS, check /dev/tty.usbserial-* 4. Make sure you have the necessary permissions 5. For Bluetooth: Make sure no other app is connected to the device ``` ## Sending Messages ### Broadcast to All Nodes ``` You: Send "Hello everyone on the mesh!" to all nodes Claude: I'll broadcast your message to the mesh network. ✓ Message sent to ^all: Hello everyone on the mesh! ``` ### Send to Specific Node ``` You: Send "Are you there?" to node !a1b2c3d4 Claude: Sending your message to that specific node... ✓ Message sent to !a1b2c3d4: Are you there? ``` ### Emergency Alert ``` You: Send an alert: "Need assistance at hiking trail marker 5" Claude: I'll send that as a high-priority alert message. ✓ Alert sent to ^all: Need assistance at hiking trail marker 5 ``` ### Request Acknowledgment ``` You: Send "Status check" to node !a1b2c3d4 and request acknowledgment Claude: Sending message with acknowledgment request... ✓ Message sent to !a1b2c3d4 on channel 0: Status check (ACK requested) ``` ## Receiving Messages ### Check Recent Messages ``` You: Show me the last 5 messages Claude: Here are the last 5 messages received: [ { "from": "!a1b2c3d4", "to": "^all", "text": "Good morning mesh!", "time": "2025-10-27T08:30:15", "portnum": "TEXT_MESSAGE_APP" }, ... ] ``` ### Monitor for Specific Content ``` You: Have I received any messages about the weather? Claude: Let me check your recent messages... Yes, I found these weather-related messages: - From !xyz123 at 9:15 AM: "Storm coming in from the west" - From !abc456 at 9:30 AM: "Heavy rain expected this afternoon" ``` ## Network Information ### View All Nodes ``` You: Show me all nodes in the mesh network Claude: Here are all the nodes currently in your mesh network: Mesh nodes: [ { "id": "!a1b2c3d4", "user": { "longName": "Mountain Relay", "shortName": "MTN1" }, "snr": 8.5, "lastHeard": "2025-10-27T10:15:30" }, ... ] You have 7 active nodes in the mesh. ``` ### Node Details ``` You: Tell me more about node !a1b2c3d4 Claude: Here's detailed information about that node: Node info: { "id": "!a1b2c3d4", "user": { "longName": "Mountain Relay", "shortName": "MTN1", "macaddr": "..." }, "position": { "latitude": 37.7749, "longitude": -122.4194, "altitude": 150 }, "snr": 8.5, "lastHeard": 1730012130 } ``` ### Local Device Info ``` You: What's the status of my local Meshtastic device? Claude: Let me get your device information... Local node info: { "num": 123456789, "user": { "longName": "My Device", "shortName": "MY1" }, "battery": 87, ... } ``` ## Traceroute ### Discover Path to Node ``` You: Send a traceroute to node !a1b2c3d4 Claude: Sending traceroute request with hop limit 7... ✓ Traceroute request sent to !a1b2c3d4 with hop limit 7 Use 'get_traceroute_results' to see the response. You: Show me the traceroute results Claude: Here are the traceroute results: Traceroute results: { "!a1b2c3d4": { "route": ["!12345678", "!abcdef12", "!a1b2c3d4"], "time": "2025-11-18T10:30:45", "snr_towards": [8.5, 6.2, 7.1], "snr_back": [8.0, 6.5, 7.3] } } ``` ## Telemetry ### Request Device Metrics ``` You: Request device telemetry from all nodes Claude: Sending telemetry request (device_metrics) to ^all Use 'get_telemetry_results' to see responses. You: Show me the telemetry data Claude: Here's the telemetry data received: Telemetry data: { "!a1b2c3d4": { "data": { "batteryLevel": 87, "voltage": 4.15, "channelUtilization": 12.5, "airUtilTx": 2.3 }, "time": "2025-11-18T10:32:15" } } ``` ### Request Environment Metrics ``` You: Request environment telemetry from the base station Claude: Sending telemetry request (environment_metrics) to !a1b2c3d4 Use 'get_telemetry_results' to see responses. ``` ## Location Sharing ### Share Current Position ``` You: Send my position at latitude 37.7749, longitude -122.4194 Claude: I'll broadcast your position to the mesh network. ✓ Position sent to ^all: 37.7749, -122.4194, 0m ``` ### Share Position with Altitude ``` You: Share my location at 45.5231 N, 122.6765 W, altitude 100 meters Claude: Broadcasting your position with altitude... ✓ Position sent to ^all: 45.5231, -122.6765, 100m ``` ## Waypoint Management ### Create Waypoint ``` You: Create a waypoint called "Camp Alpha" at coordinates 37.7749, -122.4194 with description "Main campsite" Claude: Creating waypoint... ✓ Waypoint 'Camp Alpha' sent to ^all at (37.7749, -122.4194) You: Create a waypoint "Water Source" at 37.7750, -122.4195 with icon 5 that expires in 86400 seconds Claude: Creating waypoint with icon and expiration... ✓ Waypoint 'Water Source' sent to ^all at (37.7750, -122.4195) ``` ### Delete Waypoint ``` You: Delete waypoint ID 12345 Claude: Sending waypoint deletion request... ✓ Waypoint 12345 deletion request sent to ^all ``` ## Channel Management ### List Channels ``` You: What channels are configured on my device? Claude: Here are your configured channels: Channels: [ { "index": 0, "name": "LongFast", "role": "PRIMARY" }, { "index": 1, "name": "hiking-group", "role": "SECONDARY" } ] ``` ## Device Management ### Get Device Metadata ``` You: What's my device metadata? Claude: Here's your device metadata: Device metadata: { "firmwareVersion": "2.2.15", "hwModel": "TBEAM", "hasWifi": true, "hasBluetooth": true, "canShutdown": true, "region": "US" } ``` ### Set Device Owner ``` You: Set my device owner to "John Doe" with short name "JD" Claude: Setting device owner information... ✓ Owner set: John Doe (JD) You: Set my device owner to "Jane Smith" short name "JS" and mark as licensed operator Claude: Setting licensed operator information... ✓ Owner set: Jane Smith (JS) ``` ### Reboot Device ``` You: Reboot my device in 30 seconds Claude: Sending reboot command... ✓ Reboot command sent. Device will reboot in 30 seconds. ``` ### Shutdown Device ``` You: Shutdown the device Claude: Sending shutdown command... ✓ Shutdown command sent. Device will shutdown in 10 seconds. ``` ### Show Network Information ``` You: Show me formatted network information Claude: Here's the formatted network information: Network information: Node ID: !12345678 Long Name: My Base Station Short Name: BASE Connected Nodes (5): 1. Relay-1 (!a1b2c3d4) - SNR: 8.5 dB - Last heard: 2m ago 2. Mobile-1 (!def45678) - SNR: 6.2 dB - Last heard: 5m ago ... ``` ## Advanced Use Cases ### Network Health Check ``` You: Give me a complete network health report Claude: Let me gather comprehensive information about your mesh network... Network Health Summary: - Total nodes: 7 - Nodes heard in last hour: 5 - Average SNR: 7.2 dB - Your device battery: 87% - Active channels: 2 Recent activity: - 12 messages in the last hour - 3 new nodes joined today Telemetry Summary: - Average battery across network: 75% - Channel utilization: 12.5% - All nodes reporting normal temperatures ``` ### Comprehensive Traceroute Analysis ``` You: Send traceroutes to all nodes and show me the network topology Claude: Sending traceroute requests to all discovered nodes... ✓ Traceroute sent to !node1 ✓ Traceroute sent to !node2 ✓ Traceroute sent to !node3 [Wait a few moments] You: Show me the traceroute results Claude: Here's the network topology based on traceroutes: Network Topology: Your Node → !relay1 (SNR: 8.5) → !node1 (SNR: 6.2) Your Node → !relay1 (SNR: 8.5) → !relay2 (SNR: 7.1) → !node2 (SNR: 5.8) Your Node → !node3 (SNR: 9.2) [direct connection] ``` ### Automated Monitoring ``` You: Check for any messages from !a1b2c3d4 and if there are any, summarize them Claude: Let me check messages from that node... I found 3 messages from !a1b2c3d4 (Mountain Relay): 1. Weather warning about incoming storm 2. Request for radio check 3. All clear signal Summary: This node has been active with weather updates and operational checks. ``` ### Group Coordination ``` You: Send a message to all nodes: "Team meeting at campsite B in 30 minutes" Claude: Broadcasting coordination message... ✓ Message sent to ^all: Team meeting at campsite B in 30 minutes Would you like me to monitor for any responses? ``` ## Tips for Best Results 1. **Connection**: Always connect to your device first before using other commands 2. **Node IDs**: Node IDs typically start with `!` (e.g., `!a1b2c3d4`) 3. **Broadcast**: Use `^all` or just omit the destination to broadcast to everyone 4. **Message History**: The server keeps messages in memory - they reset when restarted 5. **Natural Language**: You can use natural language - Claude will understand and call the appropriate tools ## Combining Features ### Location + Message ``` You: Send my location at 40.7128 N, 74.0060 W and also send a message saying "Arrived at checkpoint 3" Claude: I'll share both your location and status update... ✓ Position sent: 40.7128, -74.006, 0m ✓ Message sent to ^all: Arrived at checkpoint 3 Both updates broadcast successfully! ``` ### Network Analysis ``` You: Show me which nodes have the strongest signal and when they were last heard from Claude: Let me analyze your mesh network... Strongest Signals: 1. !abc123 (Base Station) - SNR: 12.5 dB - Last heard: 2 min ago 2. !def456 (Relay 1) - SNR: 9.8 dB - Last heard: 5 min ago 3. !ghi789 (Mobile 1) - SNR: 7.2 dB - Last heard: 8 min ago These nodes have excellent connectivity to your device. ``` ## Error Handling The MCP server provides helpful error messages: ``` You: Send a message to node !invalid Claude: Attempting to send message... Error: Node !invalid not found in network Would you like me to show you the available nodes? ``` ## Pro Tips - **Keep the connection alive**: Once connected, the server maintains the connection - **Message formatting**: Keep messages under 237 bytes for best compatibility - **Position updates**: GPS coordinates should be in decimal format - **Monitoring**: Check messages periodically to stay updated with the network - **Battery awareness**: Broadcasting frequently can drain battery faster - **Use alerts for emergencies**: Alert messages generate special notifications on receiving devices - **Traceroute timing**: Wait 10-30 seconds after sending traceroute before checking results - **Telemetry types**: Request specific telemetry types (device_metrics, environment_metrics, power_metrics, air_quality_metrics) - **Waypoint icons**: Use icon IDs 0-63 for different waypoint types - **Device management**: Use reboot delays wisely - give yourself time to save work