syncthing-simple-mcp

A Model Context Protocol (MCP) server for Syncthing. Lets AI agents manage Syncthing folders — add, share, remove, and check status — through the Syncthing REST API.

Built for use with MCP-compatible clients like OpenCode, Claude, Cursor, and others.

Features

• List folders — every configured folder with path, type, and shared devices
• List devices — all known peer device IDs and names
• Add folder — register a local folder with auto-generated folder ID
• Share folder — share a folder with one or more devices in a single call
• Remove folder — unlink a folder from Syncthing without touching files on disk
• Folder status — sync state, bytes, and file counts

Installation

npm install -g syncthing-simple-mcp

Or run directly with npx (no install):

npx -y syncthing-simple-mcp

Configuration

The server discovers your Syncthing API key automatically by reading config.xml from the standard locations:

| OS | Config path | |---|---| | Windows | %LOCALAPPDATA%\Syncthing\config.xml | | macOS | ~/Library/Application Support/Syncthing/config.xml | | Linux | ~/.local/state/syncthing/config.xml |

Set environment variables to override auto-discovery:

| Variable | Description | Default | |---|---|---| | STHING_API_KEY | Syncthing REST API key from the GUI settings | auto-discovered | | STHING_URL | Syncthing GUI/REST API address | http://127.0.0.1:8384 |

Client configuration examples

OpenCode (opencode.json):

{
  "mcpServers": {
    "syncthing": {
      "command": "npx",
      "args": ["-y", "syncthing-simple-mcp"],
      "env": {
        "STHING_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "syncthing": {
      "command": "npx",
      "args": ["-y", "syncthing-simple-mcp"]
    }
  }
}

Tools reference

| Tool | Params | Description | |------|--------|-------------| | list_folders | none | All folders with id, label, path, type, and shared device IDs | | list_devices | none | All devices with id, name, compression, and addresses | | add_folder | label, path, type? | Register a new folder. Generates a unique folder ID automatically. | | share_folder | folderId, deviceIds (array) | Share a folder with one or more devices. Skips already-shared devices. | | remove_folder | folderId | Remove folder from Syncthing config. Files on disk are not deleted. | | get_folder_status | folderId | Sync state, global/local bytes and files, needs, and receive-only totals |

Folder types

| Type | Behavior | |---|---| | sendreceive (default) | Send and receive changes | | sendonly | Local changes sent to peers, remote changes ignored | | receiveonly | Remote changes accepted, local changes not sent | | receiveencrypted | For untrusted devices — data is stored encrypted |

Debugging

Set STHING_LOG_LEVEL to control log verbosity:

STHING_LOG_LEVEL=debug npx -y syncthing-simple-mcp

Available levels: debug, info (default), warn, error. Logs are written to stderr so they don't interfere with the MCP protocol on stdout.

Output notes

• All responses are deterministic JSON — easy for LLMs to parse
• Errors include descriptive messages with API status codes where available
• After config changes, the response indicates if a Syncthing restart is required

Development

git clone <repo>
cd syncthing-simple-mcp
npm install
npm run build

# Run locally
node dist/index.js

License

MIT