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:

mkdir meshtastic-mcp
cd meshtastic-mcp

2. Install dependencies:

pip install -r requirements.txt

3. 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 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:

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

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