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:

2. Install dependencies:

3. Make the server executable:

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

Replace /absolute/path/to/meshtastic-mcp/ with the actual path to your installation.

Other Clients

See

• 🌊 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

Send Messages

Network Discovery & Analysis

Location & Waypoints

Device Management

Read Messages

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:

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

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

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