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
- Clone or create the project directory:
mkdir meshtastic-mcp
cd meshtastic-mcp
- Install dependencies:
pip install -r requirements.txt
- Make the server executable:
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
{
"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 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 channelssend_alert- Send high-priority alert messagesget_messages- Retrieve recent received messages
Network Discovery
get_nodes- List all nodes in the mesh networkget_node_info- Get detailed info about a specific nodeget_local_node- Get info about the connected deviceshow_network_info- Get formatted network information
Traceroute
send_traceroute- Send traceroute request to discover path and SNRget_traceroute_results- Retrieve traceroute results
Telemetry
send_telemetry_request- Request device/environment/power/air quality metricsget_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 channelsget_device_metadata- Get hardware and firmware informationset_owner- Set device owner name and license statusreboot_node- Reboot the deviceshutdown_node- Shutdown the device
Troubleshooting
Serial Connection Issues
If you have permission issues accessing serial devices:
Linux:
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/ttyUSB0or/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:
- Add a new
Tooldefinition inlist_tools() - Add the corresponding handler in
call_tool() - Use the
meshtasticPython library for device interaction
Example: Adding a Custom Tool
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
- MCP Documentation
- Meshtastic Python Library
- Client Configuration Guide - Setup for Windsurf, Cursor, ChatGPT, and more
- Bluetooth Setup Guide - 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
- MCP protocol: See MCP Documentation
- This server: Open an issue in the repository