Meshtastic MCP Server

# MCP Client Configuration Guide This guide shows you how to connect the Meshtastic MCP server to different AI assistants and IDEs that support the Model Context Protocol. ## Table of Contents - [Claude Desktop](#claude-desktop) - [Windsurf IDE](#windsurf-ide) - [Cursor IDE](#cursor-ide) - [ChatGPT Desktop](#chatgpt-desktop) - [Generic MCP Client](#generic-mcp-client) --- ## Claude Desktop ### Configuration Location **macOS:** ``` ~/Library/Application Support/Claude/claude_desktop_config.json ``` **Windows:** ``` %APPDATA%\Claude\claude_desktop_config.json ``` **Linux:** ``` ~/.config/Claude/claude_desktop_config.json ``` ### Configuration ```json { "mcpServers": { "meshtastic": { "command": "python", "args": ["/absolute/path/to/meshtastic_mcp/server2.py"] } } } ``` ### Usage 1. Save the configuration file 2. Restart Claude Desktop completely (quit and reopen) 3. Look for the 🔌 icon in the bottom-right corner 4. Start chatting: "Connect to my Meshtastic device via serial" ### Verification Check the Claude Desktop logs for any errors: **macOS:** ```bash tail -f ~/Library/Logs/Claude/mcp*.log ``` **Windows:** ``` %APPDATA%\Claude\logs\mcp*.log ``` --- ## Windsurf IDE [Windsurf](https://codeium.com/windsurf) by Codeium supports MCP servers for enhanced AI assistance. ### Configuration Location **macOS/Linux:** ``` ~/.codeium/windsurf/mcp_settings.json ``` **Windows:** ``` %USERPROFILE%\.codeium\windsurf\mcp_settings.json ``` ### Configuration ```json { "mcpServers": { "meshtastic": { "command": "python", "args": ["/absolute/path/to/meshtastic_mcp/server2.py"], "env": {} } } } ``` ### Alternative: VS Code-style Configuration If Windsurf uses VS Code settings: 1. Open Windsurf Settings (Cmd/Ctrl + ,) 2. Search for "MCP" 3. Click "Edit in settings.json" 4. Add: ```json { "mcp.servers": { "meshtastic": { "command": "python", "args": ["/absolute/path/to/meshtastic_mcp/server2.py"] } } } ``` ### Usage 1. Restart Windsurf 2. Open the AI chat panel 3. The Meshtastic tools should be available automatically 4. Try: "Connect to my Meshtastic device and show me all nodes" ### Troubleshooting - Ensure Python is in your PATH - Check Windsurf's output panel for MCP server logs - Verify the path to server2.py is absolute --- ## Cursor IDE [Cursor](https://cursor.sh/) is an AI-first code editor with MCP support. ### Configuration Location **macOS:** ``` ~/Library/Application Support/Cursor/User/globalStorage/mcp.json ``` **Windows:** ``` %APPDATA%\Cursor\User\globalStorage\mcp.json ``` **Linux:** ``` ~/.config/Cursor/User/globalStorage/mcp.json ``` ### Configuration ```json { "mcpServers": { "meshtastic": { "command": "python", "args": ["/absolute/path/to/meshtastic_mcp/server2.py"], "disabled": false } } } ``` ### Alternative: Settings UI 1. Open Cursor Settings (Cmd/Ctrl + ,) 2. Search for "Model Context Protocol" or "MCP" 3. Click "Edit MCP Servers" 4. Add the Meshtastic server configuration 5. Save and restart Cursor ### Usage 1. Restart Cursor 2. Open the AI chat (Cmd/Ctrl + L) 3. The MCP server tools will be available 4. Ask: "What Meshtastic tools are available?" 5. Try: "Scan for Meshtastic Bluetooth devices" ### Verification Check if MCP server is loaded: 1. Open Cursor's command palette (Cmd/Ctrl + Shift + P) 2. Search for "MCP: Show Server Status" 3. Look for "meshtastic" in the list ### Troubleshooting - Check Developer Console (Help → Toggle Developer Tools) - Look for MCP-related errors - Ensure Python path is correct - Try using `python3` instead of `python` if needed --- ## ChatGPT Desktop ChatGPT Desktop app (macOS) has experimental MCP support. ### Configuration Location **macOS:** ``` ~/Library/Application Support/OpenAI/ChatGPT/mcp_config.json ``` ### Configuration ```json { "mcpServers": { "meshtastic": { "command": "python", "args": ["/absolute/path/to/meshtastic_mcp/server2.py"] } } } ``` ### Enabling MCP Support 1. Open ChatGPT Desktop 2. Go to Settings → Advanced 3. Enable "Model Context Protocol" (if available) 4. Restart the application ### Usage 1. Start a new chat 2. MCP tools should be automatically available 3. Try: "Connect to my Meshtastic device" ### Note MCP support in ChatGPT Desktop may be: - In beta/experimental - Limited to certain subscription tiers - Subject to change Check [OpenAI's documentation](https://platform.openai.com/) for the latest MCP support status. --- ## Generic MCP Client For any MCP-compatible client: ### Standard Configuration Format ```json { "mcpServers": { "meshtastic": { "command": "python", "args": ["/absolute/path/to/meshtastic_mcp/server2.py"], "env": {}, "disabled": false } } } ``` ### Environment Variables (Optional) ```json { "mcpServers": { "meshtastic": { "command": "python", "args": ["/absolute/path/to/meshtastic_mcp/server2.py"], "env": { "MESHTASTIC_DEVICE": "/dev/ttyUSB0", "MESHTASTIC_CONNECTION": "serial" } } } } ``` --- ## Testing Your Configuration ### Using MCP Inspector Test your server configuration with the official MCP Inspector: ```bash npx @modelcontextprotocol/inspector python /path/to/meshtastic_mcp/server2.py ``` This opens a web interface where you can: - See all available tools - Test tool calls - View responses - Debug issues ### Manual Testing ```bash # Test Python can run the server python /path/to/meshtastic_mcp/server2.py # Should show MCP protocol initialization # Press Ctrl+C to exit ``` --- ## Common Issues ### Python Not Found **Solution:** ```json { "command": "/usr/bin/python3", "args": ["/absolute/path/to/server2.py"] } ``` Find Python path: ```bash which python3 # or which python ``` ### Import Errors **Solution:** Install dependencies in the Python environment being used ```bash # Use the same Python as in your config /usr/bin/python3 -m pip install -r /path/to/meshtastic_mcp/requirements.txt ``` ### Permission Denied **Solution:** Make server executable ```bash chmod +x /path/to/meshtastic_mcp/server2.py ``` ### Path Issues **Always use absolute paths:** ✅ Good: ``` /Users/username/projects/meshtastic_mcp/server2.py ``` ❌ Bad: ``` ~/projects/meshtastic_mcp/server2.py ./server2.py server2.py ``` ### Server Not Showing Up 1. Check logs in your IDE/app 2. Verify Python dependencies are installed 3. Test with MCP Inspector 4. Ensure configuration file is valid JSON 5. Restart the application completely --- ## IDE-Specific Features ### Windsurf - **Cascade AI**: Can use MCP tools proactively - **Inline suggestions**: May reference Meshtastic data - **Multi-file context**: Combines MCP data with code ### Cursor - **Composer**: Can orchestrate multiple MCP tool calls - **Chat history**: Remembers Meshtastic connection state - **Tab autocomplete**: May suggest MCP tool usage ### Claude Desktop - **Projects**: Can use MCP alongside project knowledge - **Artifacts**: Can display mesh network visualizations - **Conversation context**: Maintains connection state --- ## Security Considerations ### Local Network Only MCP servers run locally and have full access to your Meshtastic device. Consider: - Using MCP only on trusted computers - Not exposing your Meshtastic device on public networks - Understanding that AI assistants will have access to all mesh data ### Access Control ```json { "mcpServers": { "meshtastic": { "command": "python", "args": ["/path/to/server2.py"], "disabled": false, "permissions": { "readOnly": false } } } } ``` Some clients may support permission controls. --- ## Advanced Configuration ### Using Virtual Environments ```json { "mcpServers": { "meshtastic": { "command": "/path/to/venv/bin/python", "args": ["/path/to/meshtastic_mcp/server2.py"] } } } ``` ### Custom Environment Variables ```json { "mcpServers": { "meshtastic": { "command": "python", "args": ["/path/to/server2.py"], "env": { "PYTHONUNBUFFERED": "1", "LOG_LEVEL": "DEBUG" } } } } ``` ### Multiple Devices Connect to different Meshtastic devices: ```json { "mcpServers": { "meshtastic-home": { "command": "python", "args": ["/path/to/server2.py"] }, "meshtastic-mobile": { "command": "python", "args": ["/path/to/server2.py"] } } } ``` Note: Each server instance maintains its own connection state. --- ## Getting Help ### Logs Most MCP clients write logs. Check: - Application logs directory - Developer console - System console/terminal ### Debugging 1. Test with MCP Inspector first 2. Check Python can import `meshtastic` module 3. Verify device connectivity separately 4. Review client-specific documentation ### Resources - [MCP Specification](https://modelcontextprotocol.io/) - [Meshtastic Documentation](https://meshtastic.org/) - [This project's README](README.md) - [Quick Start Guide](QUICKSTART.md) --- ## Example Workflows ### Windsurf: Monitor Mesh While Coding ``` You: "Connect to my Meshtastic device" Windsurf: [connects] You: "Show me all nodes and keep checking for new messages while I code" Windsurf: [displays nodes, periodically checks messages] ``` ### Cursor: Debug Mesh Network ``` You: "Connect via Bluetooth and run a comprehensive network diagnostic" Cursor: [connects, runs traceroutes, checks telemetry, analyzes SNR] You: "Which node has the weakest signal?" Cursor: [analyzes data and provides answer] ``` ### Claude: Interactive Mesh Management ``` You: "Connect to my device, get all nodes, then send a status check message to each one" Claude: [connects, lists nodes, sends messages systematically] ``` --- ## Supported MCP Clients | Client | Status | Notes | |--------|--------|-------| | Claude Desktop | ✅ Full Support | Official MCP implementation | | Windsurf IDE | ✅ Supported | Check latest Windsurf docs | | Cursor IDE | ✅ Supported | MCP in recent versions | | ChatGPT Desktop | ⚠️ Experimental | May require beta access | | Zed Editor | 🔄 Upcoming | MCP support in development | | Continue.dev | ✅ Supported | VS Code extension | --- ## Next Steps 1. Choose your preferred client 2. Add the configuration 3. Restart the application 4. Test with: "Connect to my Meshtastic device" 5. Explore the [examples](EXAMPLES.md) for inspiration Happy meshing across all your favorite tools! 📡✨