LocalSend MCP

localsend-mcp gives MCP clients tools for moving files across your local network with LocalSend.

It exposes:

• localsend_scan: scan the LAN for LocalSend devices.

• localsend_send: send explicit absolute file paths to a LocalSend target.

• localsend-mcp-inbox: optional LocalSend-compatible receiver for collecting logs or small files.

The server uses the LocalSend v2 protocol directly with Python standard-library networking. No cloud relay is used.

Security Warning

This MCP lets an authorized AI client request file transfers from your computer. Only install it in MCP clients you trust.

Safety controls:

• Sends require explicit absolute file paths.

• The server does not scan your folders to choose files.

• You can restrict sends and receives to trustedDevices.

• The inbox receiver is opt-in.

• The inbox receiver saves files only to a configured inbox directory.

• The inbox receiver echoes only small text-like files.

• This project transfers files; it does not run commands from other devices.

Related MCP server: Save-To-NAS MCP

Requirements

• Python 3.10 or newer.

• LocalSend running on the target device.

• Both devices on the same local network.

Optional:

• localsend-cli on PATH, or LOCALSEND_CLI=/absolute/path/to/localsend-cli, as a fallback sender.

Install

From a local checkout:

python3 -m pip install -e .

Then configure your MCP client:

{
  "mcpServers": {
    "localsend": {
      "command": "localsend-mcp"
    }
  }
}

Without installing, you can run the server by path:

{
  "mcpServers": {
    "localsend": {
      "command": "python3",
      "args": ["/path/to/localsend-mcp/src/localsend_mcp/server.py"]
    }
  }
}

Recommended Safe Setup

First scan for LocalSend devices:

{
  "name": "localsend_scan",
  "arguments": {
    "timeout": 3
  }
}

Copy the trusted device alias and fingerprint into:

~/.config/localsend-mcp/config.json

Example:

{
  "trustedDevices": [
    {
      "alias": "Wise Blackberry",
      "fingerprint": "A9702925B0CA2BB48F5B851F82AC4013FB23AB996E3682F24D225A1C7F7C530F"
    }
  ],
  "inboxDir": "~/Downloads/localsend-mcp-inbox"
}

If trustedDevices is empty or omitted, the server allows discovered targets. For regular use, configure trusted devices.

Set a custom config path with:

export LOCALSEND_MCP_CONFIG=/path/to/config.json

Sending Files

Send to a trusted alias:

{
  "name": "localsend_send",
  "arguments": {
    "target": "Wise Blackberry",
    "files": ["/home/me/Downloads/report.pdf"]
  }
}

Send to a known URL:

{
  "name": "localsend_send",
  "arguments": {
    "target": "https://192.168.1.50:53317",
    "files": ["/home/me/Pictures/image.png"],
    "pin": "123456"
  }
}

If the receiving LocalSend app is still finishing the previous transfer, localsend_send retries busy-session responses by default:

{
  "name": "localsend_send",
  "arguments": {
    "target": "Wise Blackberry",
    "files": ["/home/me/file.txt"],
    "busy_retry_seconds": 90,
    "busy_retry_interval": 3
  }
}

Optional Inbox Receiver

Start a receiver:

localsend-mcp-inbox

It advertises itself on LocalSend as Codex MCP Inbox by default and saves received files to:

~/Downloads/localsend-mcp-inbox

Change the alias:

LOCALSEND_INBOX_ALIAS="My MCP Inbox" localsend-mcp-inbox

Change the inbox directory:

localsend-mcp-inbox --dir ~/Desktop/mcp-inbox

For best compatibility with the LocalSend mobile apps, run the inbox on the default LocalSend port with HTTPS:

localsend-mcp-inbox --port 53317 --protocol https

This generates a local self-signed certificate under ~/.config/localsend-mcp/ if one does not already exist. Do not run the desktop LocalSend app on the same machine at the same time if it also needs port 53317.

When trustedDevices is configured, the inbox rejects upload requests from untrusted senders.

LocalSend Tips

• LocalSend discovery uses UDP multicast 224.0.0.167:53317.

• Some networks block multicast; direct IP or URL targets may be more reliable.

• LocalSend HTTPS uses self-signed certificates. This server accepts those certificates for LAN transfers.

• LocalSend Quick Save or auto-save can avoid manual receive prompts, but enable it only for devices you trust.

Troubleshooting

No LocalSend device matched alias

Run localsend_scan, confirm both devices are on the same network, and make sure LocalSend is open.

Refusing to send to untrusted LocalSend device

Add the device alias, IP, or fingerprint to trustedDevices.

Blocked by another session

The receiver is busy with a prior LocalSend transfer. The sender retries by default, but enabling LocalSend auto-save on trusted devices helps.

Read operation timed out

The receiver may be waiting for user approval or the network may be blocking the transfer. Accept the transfer in LocalSend or increase timeout.

License

MIT