syncthing-mcp

MCP connector for a self-hosted Syncthing v2.1.7 GUI REST API. It speaks official /rest JSON over stdio and over stateless Streamable HTTP on localhost.

Syncthing is MPL-2.0 software (LICENSE in the v2.1.7 source and binary tree). This connector is MIT. It does not copy Syncthing source, man pages, or licence-restricted specs. It is not affiliated with syncthing/syncthing.

spec/api-inventory.json is a compact extraction of every GUI REST route registered in v2.1.7 lib/api/api.go plus expanded methods and {id} paths from lib/api/confighandler.go. It records the release version, MPL-2.0, lib/api/api.go sha256, lib/api/confighandler.go sha256, man/syncthing-rest-api.7 sha256, and routeTreeSha256. scripts/gen-operations.mjs maps that inventory onto tool actions or exclusions and writes src/operations.ts and syncthing.routes.json. A route that is neither mapped nor excluded fails generation. Do not edit src/operations.ts by hand. Default generation and npm run ci read only the committed inventory.

SYNCTHING_URL and SYNCTHING_API_KEY are required. There is no default origin and no read of ~/.config/syncthing. The connector does not start a Syncthing process. Each request sends X-API-Key as documented in man/syncthing-rest-api.7 at v2.1.7. Official /rest/noauth/health is the unauthenticated health exception.

Setup

npm install
npm run ci
npm start
npm run start:http

npm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication of its own. Keep it on localhost.

{
  "mcpServers": {
    "syncthing": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "SYNCTHING_URL": "http://127.0.0.1:8385",
        "SYNCTHING_API_KEY": "...",
        "SYNCTHING_ALLOW_WRITES": "false"
      }
    }
  }
}

The key is the GUI API key from the self-hosted instance. It is not a session cookie. The connector never prints it.

HTTP mode has no authentication of its own. Keep it on localhost. Do not put secrets in a Docker image.

docker build -t syncthing-mcp .
docker run -p 127.0.0.1:3000:3000 \
  -e SYNCTHING_URL=http://127.0.0.1:8385 \
  -e SYNCTHING_API_KEY=... \
  syncthing-mcp

Regenerate the registry from the committed inventory.

npm run gen:operations
node scripts/gen-operations.mjs --check

Refresh the inventory from an official v2.1.7 tree. This is the only command that reads route source. Keep that tree outside this MIT connector (for example /workspace/tools/syncthing/upstream).

node scripts/gen-operations.mjs --source-root /path/to/syncthing --write-inventory
node scripts/gen-operations.mjs --source-root /path/to/syncthing --check

SYNCTHING_SOURCE_ROOT is accepted by a write run. --check ignores that variable unless you also pass --source-root.

scripts/live-check.mjs talks to a real GUI over stdio. Set SYNCTHING_URL. Set SYNCTHING_API_KEY or SYNCTHING_API_KEY_FILE to a chmod 600 file outside this repo. The script unsets DATABASE_URL. It prints pass or fail lines only, and it redacts the key. It does not run inside npm run ci. A missing key is a failure.

Isolated local runtime scripts live under /workspace/tools/syncthing (start.sh, stop.sh). They generate their own config under /tmp/syncthing-mcp-runtime, never ~/.config/syncthing.

Related MCP server: Syncthing MCP

Config

Invalid values are reported by field name and issue code. The rejected value is not included.

Calls go to /rest/... paths from the operations registry. Accept is application/json. JSON writes send Content-Type: application/json. Redirects are refused so the key is not forwarded. There are no automatic retries, including HTTP 429. The API key is never placed in the URL, query, or User-Agent.

Safety

Reads run without a write flag. A write is sent only when confirm is the boolean true and SYNCTHING_ALLOW_WRITES=true. That gate covers every mutation in the registry: folder and device add/patch/remove, options patch, scan, pause, resume, error clear, restart, and shutdown. Omit confirm, or pass boolean false, and the tool returns a dry-run preview of method, path, query, and body. It sends nothing. blocked is false on that preview, whether or not writes are enabled. confirm: true with writes disabled returns the same preview with blocked true and the reason SYNCTHING_ALLOW_WRITES is not true. The write was not sent. The string "true" is rejected.

Omitted fields are dropped. paused: false, delay: 0, and an empty sub are sent when you set them. Top-level document: null is rejected because document must be a JSON object. Nested null values inside that object are sent as JSON null. A field that is not valid for the selected action is rejected before any request is sent. Unknown fields are rejected.

HTTP 401 is unauthorized. HTTP 403 is forbidden. HTTP 400 and 422 are invalid input. HTTP 404 is not found. HTTP 409 is conflict. HTTP 429 includes Retry-After when the header is present. Other failures are server, network, or timeout. Response bodies are capped at 1,000,000 bytes.

Every non-empty string or number under a sensitive key on that request is a secret, at any nesting depth and inside arrays or objects below that key, including 1-character values and values longer than 64 characters. Sensitive keys include apiKey/apikey, password, passwordHash, bindPassword, encryptionPassword, token, secret, session, cookie, authorization, credential, passphrase, privateKey, and similar names. Two real Syncthing settings that match the pattern but hold no credential, gui.sessionCookieDurationS and gui.sessionCookiePath, are returned unchanged. The configured API key (minimum 8 characters) and any URL userinfo found in the request are included too. Secrets are collected once per request and are not kept for the next call.

Sensitive-key values become [redacted] in objects. Substring masking of free text (raw, percent-encoded, and JSON-escaped forms) runs only for secrets of length 8 or more, the same floor as the API key. Percent-encoded forms match upper-case and lower-case hex. URL userinfo (scheme://user:pass@) in any returned or logged string becomes scheme://[redacted]@, so device addresses in GET /rest/config and its cached copy carry no credentials. If the request carries a shorter credential, upstream free-text error bodies and log detail are replaced with upstream detail omitted because this request carried a short credential instead of substring replacement, which would mangle this connector's own words and still leak. Object keys and this connector's preview envelope (method, path, summary, executed, and the other write-gate fields) are not rewritten. That rule covers MCP success results, MCP error text, write previews, HTTP and network errors, every logger line (including lines emitted inside the HTTP client), and config GET output.

GET /rest/config returns { config, warnings }. gui.apiKey, gui.password, and passwordHash become [redacted] placeholders. The warning is gui.apiKey, gui.password, and passwordHash are redacted placeholders. Do not PUT this document back. Use PATCH on folders, devices, or options. Full PUT /rest/config and GUI put/patch are excluded so a redacted document cannot be written back through this connector.

POST add takes one JSON object (document). Official collection PUT routes that expect JSON arrays are excluded as whole-list replace. PATCH merge is the registered edit so false, 0, and empty strings can be sent without wiping sibling keys.

Tools

Five tools. Each takes action plus the fields for that action. Fields for a different action are rejected.

health calls GET /rest/noauth/health and returns the JSON body. v2.1.7 responds {"status":"OK"}. The connector's own Streamable HTTP GET /health is separate and returns the plain text ok. add and patch need document as a JSON object. get, patch, and remove need id. db status, need, file, errors, and scan take folder. file also needs file. completion takes folder and/or device. pause may take device. scan may take sub and delay, including delay: 0 and sub: "".

36 of 97 expanded v2.1.7 REST routes are mapped. 61 are excluded. The registry has 36 actions and 13 writes. See syncthing.routes.json for every mapping and exclusion reason.

Coverage and exclusions

Useful JSON management is in scope: system health/version/status/connections/discovery, folder and device CRUD plus pending reads, folder status/need/file/errors/statistics, scan, pause/resume, restart/shutdown, config get and options patch.

Excluded with a stored reason, grouped:

• Auth and session: /rest/noauth/auth/password, /rest/noauth/auth/logout.

• GUI listener and secrets: GET/PUT/PATCH /rest/config/gui. Changing listen address or API key can shut the connector out.

• Full replace: PUT /rest/config, PUT collection /rest/config/folders and /rest/config/devices (JSON arrays), PUT per-id folder/device, PUT/POST deprecated /rest/system/config.

• LDAP bind credentials: GET/PUT/PATCH /rest/config/ldap.

• Defaults and ignores: /rest/config/defaults/*, GET/POST /rest/db/ignores.

• Debug, profile, logs, support dumps: /rest/debug/*, /rest/system/log, /rest/system/log.txt, /rest/system/loglevels.

• Host filesystem: /rest/system/browse, /rest/db/browse, /rest/system/paths.

• Self-healing and file restore: POST /rest/db/override, POST /rest/db/revert, POST /rest/folder/versions.

• Upgrade, reset, events: POST/GET /rest/system/upgrade, POST /rest/system/reset, GET /rest/events, GET /rest/events/disk.

• Deprecated aliases: /rest/config/insync, /rest/system/config/insync, /rest/folder/pullerrors, POST /rest/system/ping.

• Helpers outside lean management: /rest/svc/*, /rest/db/prio, /rest/db/localchanged, /rest/db/remoteneed, pending DELETE reject, POST /rest/system/error.

There is no arbitrary HTTP method/path passthrough.

Source provenance

Official latest stable release checked via the GitHub releases API: v2.1.7, released 21 Oct 2026. Linux amd64 binary:

https://github.com/syncthing/syncthing/releases/download/v2.1.7/syncthing-linux-amd64-v2.1.7.tar.gz

Checksum manifest sha256sum.txt.asc alongside. Verified tarball sha256 2edc416e7ed136b7c858ed5f3f02a3b8316589605e54c380228ceea7acbf0142.

Pinned inventory hashes:

The man page confirms REST on the GUI port, the X-API-Key header, and /rest/noauth as the health exception. Public docs URLs returned 404 to the fetch used during this build; inventory comes from the release-pinned source and man page instead.

Other MCP servers

Read 8 Nov 2026. Folder/device CRUD, scan, pause, resume, restart, and config already exist in the strongest rivals. Those API operations are not unique here.

nicholaswilde/syncthing-mcp-rs (main README, about 48 tools) is a full management server: patches, dry-run semantic previews on patch_instance_config and replicate_config, GUI credential masking, tests, multi-instance, and HTTP auth. It is not a read-only toy.

• src/tools/devices.rs manage_devices: add (72–83), remove (85–95), pause (97–109), resume (111–123), and approve (53–70) call client.add_device / remove_device / patch_device immediately. There is no confirm argument and no write-environment gate on those actions.

• README maintain_system force-rescans, restarts, or shuts down. Source maintain_system also has a "shutdown" arm that calls client.shutdown().await? and an upgrade arm.

• README advertises automatic API retry. src/api/client.rs uses tokio_retry send_with_retry, retry_max_attempts.unwrap_or(3), and .danger_accept_invalid_certs(config.no_verify_ssl.unwrap_or(true)).

• README also lists delete_conflict, resolve_conflict, monitor_self_healing, browse_folder, and perform_upgrade. This connector excludes conflict-delete helpers, automatic self-healing mutations, host browsing, and upgrades.

Zdendys79/mcp-server-syncthing (master README plus src/index.ts): eight tools (status, folders, folder status, folder errors, file info, scan, devices, connections). SYNCTHING_API_URL defaults to http://localhost:8384. The syncthing_scan_folder handler (lines 312–320) builds /rest/db/scan?... and await syncthingApi(endpoint, "POST") with no confirm or env gate. Uniform code-level write gating is a verified advantage against this server, not only a client UI approval.

epichub/syncthing-mcp README (8 Nov 2026) advertises 35 tools and clones zaphodsdad/syncthing-mcp. It already has folder/device CRUD, pause/resume, restart, full config, scan_folder, override_folder, and revert_folder. Those operations are not missing there. This connector maps override/revert as excluded self-healing mutations.

gladcow/syncthing_mcp_srv (master README): one sync tool plus syncthing://devices and syncthing://folders resources. Default SYNCTHING_HOME is ~/.config/syncthing. "If Syncthing is not already running, the server starts it automatically on the first request." This connector does not read the user config directory and does not auto-start Syncthing.

Honest differences that still hold after those reads:

• Every mutation, including scan, needs boolean confirm: true and SYNCTHING_ALLOW_WRITES=true.

• Omitted or false confirm always returns a method/path/query/body preview with zero HTTP writes.

• No automatic retries (especially 429). TLS verification is not disabled.

• Origin and API key are required and explicit. No ~/.config/syncthing and no auto-start.

• No conflict-delete helpers, override/revert, upgrade, or host filesystem browsing.

• Source-pinned v2.1.7 inventory with an offline generator --check.

nicholaswilde already has dry-run on some config patches, GUI masking, and tests. It does not apply a uniform confirm-plus-env gate on device add/remove/pause or on maintain_system restart/shutdown. If a later rival adds that same two-key gate on every write, this would no longer be a unique protection.

Limitations

• Collection PUT routes that expect JSON arrays are excluded. Add one folder or device with POST document as an object. Edit with PATCH.

• GET /rest/config redacts GUI secrets. Do not treat the returned document as a PUT body.

• Live bad API keys from v2.1.7 returned HTTP 403 CSRF Error, not 401. Missing folder ids returned HTTP 404 No folder with given ID. Unit tests still simulate 401, 422, and 429.

• REST POST /rest/system/restart forks a new process. A pidfile written at serve start can become stale; stop.sh also stops the verified binary still listening on the GUI port.

• The connector never starts or stops the user's Syncthing. Isolated live scripts under /workspace/tools/syncthing are throwaway only.

• A short credential (under 8 characters) that is spelled the same as an object key or a word in this connector's own preview envelope still appears there as that key or word. Values that contain it are redacted, and upstream free text is replaced. Use credentials of 8 or more characters.

• Events, logs, debug profiles, LDAP, GUI settings, ignores, restore, and upgrades stay out of the tool list.

Live check

See LIVE-CHECK.md for the checks that actually ran, including first-start notes. npm run live-check is not part of npm run ci.

npm run ci typechecks, lints, tests, and builds. node scripts/gen-operations.mjs --check reports 36 mapped routes, 61 excluded, 36 tool actions, and 97 spec routes.

Run unset DATABASE_URL, set SYNCTHING_URL, and set SYNCTHING_API_KEY or SYNCTHING_API_KEY_FILE. Then run npm run live-check. The script never prints the API key.

License

MIT. Syncthing itself is MPL-2.0. This connector only talks to the published GUI REST API.