Syncthing MCP
Provides tools for interacting with one or more Syncthing instances through the Syncthing API. Read-only by default, it exposes monitoring and operational capabilities such as system/folder status overviews, device and folder listing, connection and event inspection, and disk events, with paginated and bounded responses. Optional write, destructive, and administrative gates enable mutations such as triggering scans, changing folder destinations within allowed path roots, and trust/sharing/security administration, with multi-instance selection and per-instance credentials.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Syncthing MCP show my Syncthing folder sync status and any errors"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Syncthing MCP
A configurable Model Context Protocol server for Syncthing, using the official Python MCP SDK. Supports stdio and authenticated Streamable HTTP, multiple instances, typed operations, bounded responses, and opt-in writes. Tested against Syncthing 2.1.5.
Read-only by default. Destructive and administrative operations require separate environment gates. Disabled tools are absent from discovery and rejected by the service layer. There is no arbitrary REST proxy.
Run
Python 3.12 or newer; install the locked release from this repository:
uv sync --locked --no-dev
export SYNCTHING_URL=http://127.0.0.1:8384
export SYNCTHING_MCP_API_KEY_FILE=/run/secrets/syncthing-api-key
uv run --no-sync syncthing-mcpThe default transport is stdio. Configure your MCP client to launch that command with these environment variables. Standard output is reserved for MCP messages.
For HTTP, add:
export SYNCTHING_MCP_TRANSPORT=http
export SYNCTHING_MCP_HOST=127.0.0.1
export SYNCTHING_MCP_PORT=8080
export SYNCTHING_MCP_AUTH_TOKEN_FILE=/run/secrets/mcp-bearer-token
export SYNCTHING_MCP_ALLOWED_HOSTS='["127.0.0.1:8080"]'
uv run --no-sync syncthing-mcpConnect at http://127.0.0.1:8080/mcp with Authorization: Bearer <mcp-token>. Generate an independent random token of at least 32 characters; never reuse Syncthing's key. HTTP is stateless with JSON responses; standalone SSE GET and subscriptions are not supported. Both modern SDK v2 and actual SDK v1 clients are tested.
This static bearer mode is for trusted private deployments, not a full MCP OAuth authorization server. Use HTTPS at a reverse proxy for remote access, pass the Authorization header, set the exact external Host allowlist, and restrict network access. /healthz and /readyz are public, process-only health checks. They intentionally do not check Syncthing availability.
Published container: ghcr.io/sharkusmanch/syncthing-mcp. Use a release tag and verified digest, bind HTTP to 0.0.0.0 inside the container, run as UID/GID 10001, with a read-only filesystem and no capabilities. No Syncthing data volume is needed. The digest-pinned Chainguard Python runtime contains no shell or package manager; use python for operational probes.
Related MCP server: immich-mcp
Configure coverage and authority
All settings below use the SYNCTHING_MCP_ prefix unless shown otherwise. Lists accept JSON arrays (preferred) or comma-separated names. Unknown tool/group names and invalid booleans fail startup. Booleans accept exactly true or false.
Setting | Default / purpose |
| Single backend URL and key; alternatively |
| JSON list of |
|
|
|
|
| HTTP client credential; supply only one |
| Exact HTTP Host values, including port when present; set explicitly for HTTP clients |
| Empty; supplied Origin must match exactly, absent Origin is allowed |
|
|
| Optional group allowlist; diagnostics excluded unless explicitly enabled |
| Optional exact tool allowlist, replacing profile selection but never bypassing permissions |
| Exact denylist, always wins |
|
|
|
|
|
|
| Single-instance destination roots; empty denies destination changes; |
| Optional CA bundle for upstream HTTPS; certificate validation cannot be disabled |
| 30 / 300 seconds; overview shares one request deadline across all folder reads; scan has a longer finite deadline |
| 262144; HTTP body and tool argument budget |
| 262144; HTTP response and tool-result budget |
| 4194304; maximum streamed upstream response |
| 100; ceiling for list operations |
| 8; upstream calls and active HTTP request ceiling |
| 120 authenticated requests per minute, shared-principal token bucket |
Examples:
# Small monitoring catalog:
export SYNCTHING_MCP_PROFILE=core
# Broader reads are the default. Exact exclusions can narrow them:
export SYNCTHING_MCP_DISABLED_TOOLS='["syncthing_events","syncthing_disk_events"]'
# Ordinary writes, without destructive or administrative authority:
export SYNCTHING_MCP_ALLOW_WRITES=trueMultiple instances:
[
{"name":"hub","url":"https://syncthing.example:8384","api_key_file":"/run/secrets/hub-key"},
{"name":"lab","url":"http://syncthing-lab:8384","api_key_file":"/run/secrets/lab-key","allowed_paths":["/data"],"path_style":"posix"}
]One bearer authorizes all configured instances. Read calls without an instance select the first configured instance; writes require an explicit instance when more than one exists. There are no per-user or per-folder read ACLs. Use separate deployments for separate trust domains. Path roots constrain destination changes, not data visibility; they are lexical checks, not protection against symlinks on the remote host.
See coverage for tool names and exclusions, mutation policy for accepted fields and outcomes, and security for the trust boundary.
Results and token use
Discovery is deterministic and paginated. Lists return bounded pages with returned, next_cursor, truncated, and pagination semantics. fields selects top-level fields after safe configuration projection; it cannot recover hidden secrets. Offset pages reflect live state and are not stable snapshots. Event retention can create gaps; event results report completeness limitations explicitly.
Overview returns partial: true when folder status reads fail or exhaust its aggregate request deadline. Completed statuses are retained, unavailable statuses are null, and deadline_exceeded distinguishes budget exhaustion. Failure before the initial system/folder snapshot returns an error.
Configuration credentials and unknown configuration fields are omitted. Diagnostic tools expose potentially sensitive operational text and are off by default. Known-secret redaction is defense in depth; arbitrary remote text is untrusted data, never an instruction to the client.
Tool output includes structured content and compact JSON text for older clients. Errors use isError and sanitized codes. Oversized results return an actionable error instead of malformed/truncated JSON. Complete HTTP envelopes are capped, including SDK metadata and reflected request IDs. The official stdio transport reads complete lines before validation: its framing and request IDs are not protected by the HTTP byte cap. Stdio is intended for a trusted local parent process; tool argument/result limits still apply.
Measured catalog/result sizes and the reproducible measurement command are recorded in efficiency. Bytes are reported directly; token counts depend on the client's tokenizer.
Build, verify and maintain
uv sync --locked --group dev --group build
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest --cov=syncthing_mcp --cov-branch --cov-fail-under=80
uv run --project tests/legacy-client --locked python scripts/legacy_smoke.py --server-python "$PWD/.venv/bin/python"
sh scripts/install-test-syncthing.sh /tmp/syncthing-fixture
SYNCTHING_TEST_BINARY=/tmp/syncthing-fixture/syncthing-linux-amd64-v2.1.5/syncthing uv run pytest tests/test_live_syncthing.py
uv sync --locked --group dev --group build
uv build --no-build-isolationThe live test creates a temporary Syncthing profile, disables discovery/relays/NAT/upgrades, removes default folders, and only mutates disposable data. CI gates releases on those tests, Python 3.12/3.14, lint, types, coverage, runtime dependency auditing, and a restricted container smoke test.
Release workflow builds linux/amd64 and linux/arm64 images, emits per-platform BuildKit SBOM/provenance, scans both platform digests, signs the multiarch index with GitHub artifact attestations, verifies it, then promotes that exact digest to release tags. Release verification explains independent verification. Renovate GitHub App configuration maintains dependencies, lockfiles, Action SHAs and image digests; automerge is disabled.
MIT licensed. This project is independently maintained and is not an official Syncthing project.
Available Tools
40 toolssyncthing_configDRead-only
Config.
Inputs: fields, instance.
syncthing_device_configDRead-only
Device config.
Inputs: device (required), fields, instance.
syncthing_device_defaultsDRead-only
Device defaults.
Inputs: fields, instance.
syncthing_devicesDRead-only
Devices.
Inputs: limit, cursor, fields, instance.
syncthing_device_statisticsDRead-only
Device statistics.
Inputs: limit, cursor, fields, instance.
syncthing_disk_eventsDRead-only
Disk events.
Inputs: limit, since, events, fields, +2 more.
syncthing_eventsDRead-only
Events.
Inputs: limit, since, events, fields, +2 more.
syncthing_file_metadataDRead-only
File metadata.
Inputs: file (required), folder (required), fields, instance.
syncthing_file_versionsDRead-only
File versions.
Inputs: folder (required), limit, cursor, fields, +1 more.
syncthing_folder_browseDRead-only
Folder browse.
Inputs: folder (required), limit, cursor, fields, +3 more.
syncthing_folder_completionDRead-only
Folder completion.
Inputs: folder (required), device, fields, instance.
syncthing_folder_configDRead-only
Folder config.
Inputs: folder (required), fields, instance.
syncthing_folder_defaultsDRead-only
Folder defaults.
Inputs: fields, instance.
syncthing_folder_errorsDRead-only
Folder errors.
Inputs: folder (required), limit, cursor, fields, +1 more.
syncthing_foldersDRead-only
Folders.
Inputs: limit, cursor, fields, instance.
syncthing_folder_statisticsDRead-only
Folder statistics.
Inputs: limit, cursor, fields, instance.
syncthing_folder_statusDRead-only
Folder status.
Inputs: folder (required), fields, instance.
syncthing_gui_configDRead-only
Gui config.
Inputs: fields, instance.
syncthing_ignore_defaultsDRead-only
Ignore defaults.
Inputs: fields, instance.
syncthing_ignoresDRead-only
Ignores.
Inputs: folder (required), fields, instance.
syncthing_instancesCRead-only
Discover configured instance aliases and active permissions.
Inputs: fields, instance.
syncthing_languagesDRead-only
Languages.
Inputs: fields, instance.
syncthing_ldap_configDRead-only
Ldap config.
Inputs: fields, instance.
syncthing_local_changesDRead-only
Local changes.
Inputs: folder (required), limit, cursor, fields, +1 more.
syncthing_needed_filesDRead-only
Needed files.
Inputs: folder (required), limit, cursor, fields, +1 more.
syncthing_optionsDRead-only
Options.
Inputs: fields, instance.
syncthing_overviewCRead-only
Bounded overview of this instance and folder synchronization state.
Inputs: limit, cursor, fields, instance.
syncthing_pending_devicesDRead-only
Pending devices.
Inputs: limit, cursor, fields, instance.
syncthing_pending_foldersDRead-only
Pending folders.
Inputs: limit, cursor, fields, instance.
syncthing_random_stringDRead-only
Random string.
Inputs: fields, length, instance.
syncthing_remote_needed_filesDRead-only
Remote needed files.
Inputs: device (required), folder (required), limit, cursor, +2 more.
syncthing_restart_requiredDRead-only
Restart required.
Inputs: fields, instance.
syncthing_system_connectionsDRead-only
System connections.
Inputs: fields, instance.
syncthing_system_errorsDRead-only
System errors.
Inputs: fields, instance.
syncthing_system_healthDRead-only
System health.
Inputs: fields, instance.
syncthing_system_pingDRead-only
System ping.
Inputs: fields, instance.
syncthing_system_statusDRead-only
System status.
Inputs: fields, instance.
syncthing_system_versionCRead-only
System version.
Inputs: fields, instance.
syncthing_upgrade_availableDRead-only
Upgrade available.
Inputs: fields, instance.
syncthing_validate_device_idCRead-only
Validate device id.
Inputs: device (required), fields, instance.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 40 tools
Many tools are terse nouns with overlapping scopes: config vs options, devices vs device_config/defaults/statistics, folder_status vs folder_completion/statistics/errors. An agent cannot reliably tell which tool to call for a given Syncthing operation without more description.
All tools consistently use snake_case with the syncthing_ prefix, which is predictable and readable. However, they are mostly noun phrases rather than verb_noun action patterns, so the convention is consistent but not action-oriented.
40 tools is excessive for a single MCP server, especially with many terse and overlapping endpoints. Although Syncthing has a broad API, this surface is heavy and difficult to navigate.
The tools cover many read/status/config areas such as devices, folders, events, connections, and statistics, but key lifecycle operations like adding/removing folders or devices, scanning, pausing, or resuming are not clearly represented. Some CRUD coverage may exist through config tools, but it is not evident from the surface.
Maintenance
Related MCP Connectors
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Streamable HTTP MCP gateway for NV oOS fleets — one API key, namespaced tools, quotas and policy.
Toolstile is a managed MCP gateway that connects remote MCP servers behind one endpoint, with per-agent permissions, shared accounts and activity logs. Connect at https://mcp.toolstile.com/mcp over Streamable HTTP with OAuth; sign in at https://toolstile.com, select a workspace and connect your upstream servers. Available tools, resources and prompts depend on that workspace and the agent's granted access.
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
Related MCP Servers
- AlicenseCqualityBmaintenanceEnables MCP clients to inspect and manage Semaphore UI automation through its management API, covering projects, templates, tasks, logs, inventories, repositories, and related configuration. It works over stdio or Streamable HTTP with schema-validated tools, read-only mode, project allowlists, and a bounded task-wait helper.213MIT
- AlicenseAqualityCmaintenanceConnects MCP clients to a self-hosted photo library through its REST API, exposing assets, albums, people, search, and optional administrative toolsets with read-only defaults and confirm-gated writes. It supports stdio and localhost Streamable HTTP transports.5MIT
- AlicenseBqualityBmaintenanceConnects MCP clients to a self-hosted Seafile server through the seahub HTTP API, exposing libraries, files, search, sharing, and optional admin operations over stdio or Streamable HTTP. It defaults to read-focused tools and gates writes behind confirmation, with token redaction and dry-run previews.4MIT
- AlicenseAqualityCmaintenanceEnables MCP clients to interact with a self-hosted comic/library server through its HTTP API, exposing libraries, series, books, collections, readlists, metadata, and administrative operations with read/write safety controls over stdio or Streamable HTTP.7MIT