mcp-server-syncthing

MCP Server for Syncthing

MCP (Model Context Protocol) server providing tools for controlling and monitoring Syncthing via its REST API.

Features

Monitoring Tools

• syncthing_get_status - Get overall system status (version, uptime, system info)
• syncthing_list_folders - List all configured folders with IDs, labels, and paths
• syncthing_get_folder_status - Get detailed folder status (sync state, errors, byte counts)
• syncthing_get_folder_errors - Get list of errors for a specific folder
• syncthing_get_file_info - Get file information (local vs global versions)
• syncthing_list_devices - List all configured devices
• syncthing_get_connections - Get current connection status for all devices

Control Tools

• syncthing_scan_folder - Trigger folder/subfolder scan to detect changes

Installation

1. Install Dependencies

cd ~/mcp-servers/syncthing
npm install
npm run build

2. Set System Environment Variables

Option A: System-wide (Recommended)

Add to /etc/environment: ``bash SYNCTHING_API_KEY="your-api-key-here" SYNCTHING_API_URL="http://localhost:8384" ``

Then logout/login for changes to take effect.

Option B: User profile

Add to ~/.profile (NOT ~/.bashrc): ``bash export SYNCTHING_API_KEY="your-api-key-here" export SYNCTHING_API_URL="http://localhost:8384" ``

Then logout/login for changes to take effect.

Note: ~/.bashrc only works for terminal sessions, not GUI apps like Claude Desktop.

To find your API key:

• Open Syncthing web UI (usually http://localhost:8384)
• Go to Actions > Settings > General
• Copy the API Key

3. Configure Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "syncthing": {
      "command": "node",
      "args": ["/home/zdendys/mcp-servers/syncthing/dist/index.js"]
    }
  }
}

Note: Environment variables are loaded from system, not hardcoded in config.

4. Restart Claude Desktop

The MCP tools will be available in your next Claude Code session.

Usage Examples

Check System Status

syncthing_get_status()

List All Folders

syncthing_list_folders()

Get Folder Status

syncthing_get_folder_status({ folder: "zoaz2-u7tor" })

Check File Information

syncthing_get_file_info({
  folder: "zoaz2-u7tor",
  file: "minecraft/client-mods-1.21.1.zip"
})

Trigger Folder Scan

syncthing_scan_folder({ folder: "zoaz2-u7tor" })
// Or scan specific subfolder:
syncthing_scan_folder({ folder: "zoaz2-u7tor", sub: "minecraft" })

Check Connection Status

syncthing_get_connections()

Troubleshooting

API Key Not Set

If you see: [ERROR] SYNCTHING_API_KEY environment variable is not set

Solution: Make sure environment variable is set in Claude Desktop config.

Connection Refused

If you see: Syncthing API error: connect ECONNREFUSED

Solution:

• Verify Syncthing is running: ps aux | grep syncthing
• Check API URL is correct (default: http://localhost:8384)
• Verify Syncthing web UI is accessible in browser

API Key Invalid

If you see: Syncthing API error: 403 Forbidden

Solution: Double-check your API key in Syncthing settings.

Development

Build

npm run build

Watch Mode

npm run watch

Test Tools Manually

export SYNCTHING_API_KEY="your-key"
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

Architecture

• Language: TypeScript
• MCP SDK: @modelcontextprotocol/sdk
• API Client: Native fetch API
• Transport: stdio (standard input/output)

Security Notes

• API key is loaded from environment variables (never hardcoded)
• All API communication happens locally (default: localhost:8384)
• No external network requests
• Read-only operations are safe; write operations (scan) require user approval in Claude Code

License

MIT

Authors

• Zdendys (Project Manager)
• Nyara (AI Assistant)