Syncthing Mcp Rs

Coveralls task ci

[!WARNING] This project is currently in active development (v0.1.20) and is not production-ready. Features may change, and breaking changes may occur without notice. Use this MCP server at your own risk.

A Rust implementation of a Syncthing MCP (Model Context Protocol) server. This server connects to one or more Syncthing instances and exposes tools to monitor and manage file synchronization via the Model Context Protocol.

:sparkles: Features

• Multi-Transport Support:
  • Stdio: Default transport for local integrations (e.g., Claude Desktop).
  • HTTP with SSE: Remote access support via Server-Sent Events (SSE) for notifications and HTTP POST for messages.
• Multi-Instance Management: Manage and target multiple Syncthing instances from a single MCP server. Tools accept an optional instance argument (name or index).
• Instance Configuration Management: Generate detailed difference reports between instances; perform additive merges of folders and devices from a source to a target; synchronize configurations with granular control and safety previews.
• Granular Configuration Patching: Update specific folder or device settings using partial JSON patches with dry-run support and semantic diff previews.
• Network Performance Analytics: Access detailed connection protocol information, cryptographic status, and automated network diagnostics to troubleshoot connectivity issues.
• Event Timeline Analysis: Retrospective debugging and monitoring with time-windowed event summaries and basic pattern detection (e.g., rapid device flapping).
• Event Notifications: Receive real-time MCP notifications for key Syncthing events (e.g., folder state changes, device connections).
• GUI & Security Management: Retrieve and update Syncthing GUI settings, including HTTPS/TLS, authentication, and themes, with automatic masking of sensitive credentials.
• Conflict Management: Metadata-driven conflict detection and resolution with support for semantic diffing (JSON/YAML) and resolution previews.
• Robust Configuration: Supports configuration via CLI arguments, environment variables, and configuration files (TOML).
• Security & Privacy:
  • OS Keyring Integration: Securely store and retrieve API keys from the OS-level secret store.
  • Authenticated Encryption: Support for encrypted configuration fields using ChaCha20-Poly1305.
• Authentication: Connects to Syncthing using API Key (X-API-Key). Supports plain text, OS Keyring (keyring:service:account), or encrypted blobs (encrypted:v1:...).
• Resilience: Automatic retry with exponential backoff for transient network and server errors.
• Bandwidth Orchestration: Dynamic upload/download rate limiting across instances with support for scheduled performance profiles (e.g., "working_hours").
• Self-Healing Monitor: Automated detection and resolution of common Syncthing issues, including stuck folders (via rescans) and offline devices (via reconnection retries with exponential backoff).
• Version Control Integration (Git-Sync): Automatically back up Syncthing configurations to a Git repository. Supports sensitive information masking, version diffing, and rolling back to previous configurations.
• Token Usage Optimization: Optimized for LLM context windows with field aliasing, content filtering, and consolidated "super-tools" to reduce the number of turns and token overhead.
• Binary Optimization: Small footprint (approx. 2.4M) for efficient deployment.
  • Tools:
    • analyze_error: Analyze a technical error message and provide a diagnostic summary with actionable advice.
    • batch_manage_folders: Performs bulk actions (rescan, revert, pause, resume) on multiple folders simultaneously.
    • check_upgrade: Check if a newer version of Syncthing is available for the instance.
    • browse_folder: Browse the contents of a synced folder, listing files and subdirectories with optional prefix, recursion depth control, and result limiting.
    • configure_sharing: Configure folder sharing between devices (share or unshare).
    • delete_conflict: Permanently delete a Syncthing conflict file.
    • diagnose_network_issues: Analyze network connection and discovery states to troubleshoot disconnected or degraded devices.
    • diff_conflicts: Compare the original and conflict versions of a file.
    • diff_instance_configs: Returns a detailed difference report between two SyncThing instance configurations.
    • get_bandwidth_status: Get current bandwidth limits and active profiles for all SyncThing instances.
    • get_device_statistics: Get detailed connection statistics for all devices, including last seen time and last connection duration.
    • get_device_sync_status: Retrieves synchronization completion status for a specific device, optionally filtered by folder.
    • get_discovery_status: Get the current status of the local and global discovery mechanisms, listing announced addresses for all known devices.
    • get_event_timeline: Retrieves a summarized timeline of recent SyncThing events for retrospective debugging and monitoring. Includes basic intelligence to highlight critical patterns like rapid flapping.
    • get_file_info: Get detailed metadata and availability information for a specific file in a folder.
    • get_folder_needs: Get the list of files that are needed to bring a folder up to date.
    • get_folder_statistics: Get detailed statistics for all folders, including last scan time and information about the last synced file.
    • get_global_dashboard: Get a high-level overview of all configured SyncThing instances, including aggregated transfer rates and network health.
    • get_gui_settings: Retrieve the GUI/Web UI security settings for a Syncthing instance. Sensitive fields like passwords and API keys are masked.
    • get_instance_health: Get detailed health information for a specific Syncthing instance, including connectivity, version, uptime, and resource usage.
    • get_instance_overview: Provides a top-level health and status report for a SyncThing instance, consolidating system status, connections, and version information.
    • get_sync_status: Get detailed synchronization status, state, and completion percentage for a specific folder or device.
    • get_system_connections: Get the current connection status and data transfer statistics for all connected devices. Includes an 'Analytics' mode for granular Crypto and Local Network details.
    • get_system_errors: Retrieves the current list of active system GUI errors from the SyncThing instance.
    • get_system_log: Get recent log entries from the Syncthing service for troubleshooting.
    • get_system_status: Get comprehensive system status information, including version, uptime, memory usage, and the unique device ID.
    • inspect_device: Provides a comprehensive status overview for a specific device, consolidating completion status and statistics.
    • inspect_folder: Provides a comprehensive status overview for a specific folder, consolidating sync status, conflicts, and statistics.
    • is_config_insync: Checks if the running SyncThing configuration is in sync with the on-disk configuration. Returns true if in sync, false if a restart might be required.
    • list_conflicts: List Syncthing conflict files in a specific folder.
    • list_instances: List all configured Syncthing instances and their current health status.
    • maintain_system: Perform system maintenance: force a rescan of folders, restart the Syncthing service, or shut down the service.
    • manage_devices: Manage Syncthing devices: list, add, remove, pause, resume, approve pending devices, or validate device IDs.
    • manage_folders: Manage Syncthing folders: list configured folders, get a specific folder, view pending folder requests, reject pending requests, or revert local changes in Receive Only folders.
    • manage_ignores: Manage folder ignore patterns (.stignore). Supports getting current patterns, setting a new list, or appending to the existing list.
    • merge_instance_configs: Merges configuration from one SyncThing instance into another. This appends/updates folders and devices instead of replacing the entire configuration.
    • monitor_self_healing: Monitor tool that checks for stuck folders and disconnected devices, and triggers self-healing actions.
    • patch_instance_config: Update the configuration of a folder, device, or other configuration element using a partial (patch) JSON object. Supports dry run previews with semantic diffing.
    • perform_upgrade: Trigger an upgrade to the latest available version of Syncthing.
    • ping_instance: Ping the Syncthing instance to verify API responsiveness and measure latency.
    • preview_conflict_resolution: Show what the file will look like after a proposed resolution.
    • replicate_config: Replicate configuration (folders and devices) from one Syncthing instance to another. Optionally perform a dry run or select specific folders/devices.
    • resolve_conflict: Resolve a Syncthing conflict file by keeping either the original or the conflict version. Supports a preview mode.
    • set_bandwidth_limits: Set the bandwidth limits (upload/download) across one or all SyncThing instances.
    • set_file_priority: Moves a specific file to the top of the download queue for a folder.
    • set_performance_profile: Set the active performance profile (e.g., 'working_hours', 'overnight', 'full_speed').
    • summarize_conflicts: Provides an actionable summary of conflicts across all folders, grouped by folder with counts and sizes.
    • update_gui_settings: Update the GUI/Web UI security settings for a Syncthing instance.

:package: Installation

Homebrew

brew install nicholaswilde/tap/syncthing-mcp-rs

:whale: Docker

You can run the MCP server using Docker.

Build the Image

task docker:build

Run the Server

# Using environment variables
docker run --rm -e SYNCTHING_API_KEY="your-api-key" syncthing-mcp-rs

# Using an .env file
task docker:run

Docker Compose

A docker-compose.yml is provided for quick setup with a local SyncThing instance:

export SYNCTHING_API_KEY="your-api-key"
docker-compose up -d

:hammer_and_wrench: Build

To build the project, you need a Rust toolchain installed. For cross-compilation, cross is used.

Local Build

# Build in release mode
task build:local

The binary will be available at target/release/syncthing-mcp-rs. The release binary is highly optimized for size (approx. 2.4M).

Cross-Compilation

Supported architectures can be built using task:

# Build for AMD64 (x86_64)
task build:amd64

# Build for ARM64 (aarch64)
task build:arm64

# Build for all supported architectures
task build

:rocket: Usage

:keyboard: Command Line Interface

The server can be configured via CLI arguments or environment variables.

# Run the MCP server
./target/release/syncthing-mcp-rs --host "localhost" --port 8384 --api-key "your-api-key"

# Run the MCP server with HTTP/SSE enabled
./target/release/syncthing-mcp-rs --http-enabled --http-port 3000

# Encrypt a sensitive value (e.g., API key) for use in config.toml
./target/release/syncthing-mcp-rs encrypt "your-api-key"

:joystick: HTTP/SSE Remote Access

To access the server remotely, you can enable the HTTP/SSE transport.

1. Start the server:

   ./syncthing-mcp-rs --http-enabled --http-port 3000 --http-api-key "your-secret-token"
   

2. Establish an SSE connection:

   curl -N -H "Authorization: Bearer your-secret-token" http://localhost:3000/sse
   

   The first event will contain the endpoint for POSTing messages:

   event: endpoint
   data: /message?session_id=d623f749-33f6-41e2-91a4-8d440171d8ab
   

3. Send MCP messages via HTTP POST:

   curl -X POST "http://localhost:3000/message?session_id=d623f749-33f6-41e2-91a4-8d440171d8ab" \
     -H "Authorization: Bearer your-secret-token" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
   

Available Arguments

Argument	Environment Variable	Description	Default
-c, --config	-	Path to configuration file	config.toml
--host	SYNCTHING_HOST	Syncthing instance host	localhost
--port	SYNCTHING_PORT	Syncthing instance port	8384
--api-key	SYNCTHING_API_KEY	Syncthing API key (supports keyring:... and encrypted:...)	-
--transport	SYNCTHING_MCP_TRANSPORT	Transport mode (stdio)	stdio
--http-enabled	SYNCTHING_HTTP_SERVER__ENABLED	Enable the HTTP/SSE server	false
--http-host	SYNCTHING_HTTP_SERVER__HOST	HTTP server host	0.0.0.0
--http-port	SYNCTHING_HTTP_SERVER__PORT	HTTP server port	3000
--http-api-key	SYNCTHING_HTTP_SERVER__API_KEY	Bearer token for HTTP server	-
--no-verify-ssl	SYNCTHING_NO_VERIFY_SSL	Disable SSL certificate verification	true
--log-level	SYNCTHING_LOG_LEVEL	Log level (info, debug, etc.)	info
-	SYNCTHING_RETRY_MAX_ATTEMPTS	Max retries for API calls	3
-	SYNCTHING_RETRY_INITIAL_BACKOFF_MS	Initial retry backoff in ms	100
-	SYNCTHING_INSTANCES__<N>__<FIELD>	Configuration for multiple instances	-

:file_folder: Configuration File

The server automatically looks for config.toml in the current directory and ~/.config/syncthing-mcp-rs/.

Multi-Instance Configuration

# Global settings
retry_max_attempts = 3
retry_initial_backoff_ms = 100

# Default instance using OS Keyring
host = "localhost"
port = 8384
api_key = "keyring:syncthing:local-key"

# Bandwidth Orchestration (Optional)
[bandwidth]
active_profile = "working_hours"

[[bandwidth.profiles]]
name = "working_hours"
limits = { max_recv_kbps = 1000, max_send_kbps = 500 }

[[bandwidth.profiles]]
name = "full_speed"
limits = { max_recv_kbps = 0, max_send_kbps = 0 }

[[bandwidth.schedules]]
profile_name = "working_hours"
days = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
start_time = "09:00"
end_time = "17:00"

# OR use the instances list with encrypted values
[[instances]]
name = "remote"
url = "https://sync.example.com"
api_key = "encrypted:v1:4jBYSgrSQQ0JbZzLwBom99zlcKJ8549tgeSUnm4dZr+L4+1rPh0WFak="
no_verify_ssl = false

:robot: Configuration Example (Claude Desktop)

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "syncthing": {
      "command": "/path/to/syncthing-mcp-rs/target/release/syncthing-mcp-rs",
      "args": [
        "--host", "localhost",
        "--port", "8384",
        "--api-key", "your-api-key"
      ]
    }
  }
}

:test_tube: Testing

The project uses go-task for development tasks.

# Run all checks (format, lint, unit tests)
task test:ci

# Run unit tests only
task test

# Run Docker integration tests (requires Docker)
RUN_DOCKER_TESTS=true task test:integration

# Run MCP Inspector (requires npx)
task inspector

# Generate documentation
task docs

# Generate and open documentation
task docs:open

# Update cargo dependencies
task update

:bar_chart: Coverage

The project uses cargo-llvm-cov for code coverage analysis.

# Show coverage summary in console
task coverage

# Generate detailed HTML and LCOV reports
task coverage:report

# Upload coverage to Coveralls.io (requires COVERALLS_REPO_TOKEN)
COVERALLS_REPO_TOKEN=your_token task coverage:upload

:handshake: Contributing

Contributions are welcome! Please follow standard Rust coding conventions and ensure all tests pass (task check) before submitting features.

:balance_scale: License

Apache License 2.0

:writing_hand: Author

This project was started in 2026 by Nicholas Wilde.