Meshtastic MCP Server

# Quick Start Guide Get your Meshtastic MCP server up and running in 5 minutes! ## Prerequisites - Python 3.10 or higher - A Meshtastic device (T-Beam, T-Echo, Heltec, etc.) - Claude Desktop app ## Step 1: Install Dependencies ```bash pip install -r requirements.txt ``` ## Step 2: Test Your Device Connection Before setting up the MCP server, verify your Meshtastic device works: **For Serial (USB):** ```bash python test_connection.py --type serial ``` **For TCP/IP:** ```bash python test_connection.py --type tcp --device meshtastic.local ``` **For Bluetooth:** ```bash # First, scan for devices python test_connection.py --type scan # Then connect using the MAC address python test_connection.py --type bluetooth --device AA:BB:CC:DD:EE:FF ``` If this succeeds, you're ready to proceed! ## Step 3: Configure Claude Desktop 1. Find your Claude Desktop config file: - **MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` 2. Add the Meshtastic MCP server: ```json { "mcpServers": { "meshtastic": { "command": "python", "args": ["/full/path/to/meshtastic-mcp/server2.py"] } } } ``` Replace `/full/path/to/meshtastic-mcp/` with the actual path where you cloned/created this project. ## Step 4: Restart Claude Desktop Close and reopen Claude Desktop completely. ## Step 5: Test It Out! Start a conversation with Claude: ``` You: Connect to my Meshtastic device via serial # or: Scan for Meshtastic devices via Bluetooth Claude: I'll connect to your Meshtastic device... ✓ Successfully connected! You: Send a test message to all nodes Claude: Broadcasting your test message... ✓ Message sent to ^all on channel 0: test message You: Show me all nodes in the mesh Claude: Here are all the nodes in your mesh network... [lists your nodes] You: Send a traceroute to the first node Claude: Sending traceroute request... ✓ Traceroute request sent with hop limit 7 You: What's my device metadata? Claude: Here's your device metadata: [shows firmware version, hardware model, etc.] ``` ## Common Issues ### "Permission Denied" on Serial Port **Linux:** ```bash sudo usermod -a -G dialout $USER # Log out and back in ``` ### Can't Find Device Path **Find serial devices:** ```bash # Linux/Mac ls /dev/tty* # Look for something like: # /dev/ttyUSB0 (Linux) # /dev/tty.usbserial-XYZ (Mac) ``` ### MCP Server Not Showing Up in Claude 1. Check the path in your config is absolute (not relative) 2. Verify Python is in your PATH: `which python` 3. Check Claude Desktop logs for errors 4. Make sure you fully quit and restarted Claude Desktop ### Connection Timeouts - Ensure your Meshtastic device is powered on - For serial: check USB cable and ports - For TCP: verify the device is on the same network - For Bluetooth: ensure no other app is connected to the device ### Bluetooth Issues **Can't find device:** - Make sure Bluetooth is enabled on your device - Move closer to the Meshtastic device - Disconnect from the Meshtastic app on your phone **"bleak not installed":** ```bash pip install bleak ``` For more Bluetooth help, see [BLUETOOTH.md](BLUETOOTH.md) ## Next Steps Check out: - **EXAMPLES.md** - Detailed usage examples - **README.md** - Full documentation - [Meshtastic Docs](https://meshtastic.org/) - Learn about Meshtastic ## Getting Help 1. Run the test script: `python test_connection.py` 2. Check Claude Desktop logs 3. Verify Meshtastic firmware is up to date 4. Join the Meshtastic Discord: https://discord.gg/meshtastic Happy meshing! 📡