# Syncthing MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for managing and monitoring [Syncthing](https://syncthing.net/) file synchronization instances. Built with [FastMCP](https://gofastmcp.com/).

## Features

- **35 tools** for complete Syncthing management
- **Multi-instance support** - manage multiple Syncthing nodes from one server
- **Three transport modes** - streamable-http, SSE, and stdio
- **Async throughout** - non-blocking httpx client with connection pooling

## Quick Start

```bash
git clone https://github.com/zaphodsdad/syncthing-mcp.git
cd syncthing-mcp
cp .env.example .env
# Edit .env with your Syncthing instance details
uv sync
uv run syncthing-mcp
```

## Configuration

### Single Instance

```env
SYNCTHING_URL=http://localhost:8384
SYNCTHING_API_KEY=your-api-key-here
```

### Multiple Instances

```env
SYNCTHING_INSTANCES=server1|http://host1:8384|key1,server2|http://host2:8384|key2
```

### Server Options

```env
SERVER_HOST=0.0.0.0
SERVER_PORT=8088
TRANSPORT=streamable-http   # streamable-http, sse, or stdio
LOG_LEVEL=INFO
```

## Tools

### Monitoring (15 tools, read-only)

| Tool | Description |
|------|-------------|
| `list_instances` | List configured instances and check connectivity |
| `get_status` | System status: version, uptime, memory usage |
| `get_connections` | Device connections with bandwidth and addresses |
| `get_completion` | Sync completion % for a folder/device pair |
| `list_folders` | All configured folders with labels, paths, types |
| `get_folder_status` | Detailed folder sync state, file counts, errors |
| `list_devices` | All configured devices with names and addresses |
| `get_device_stats` | Per-device stats: last seen, connection duration |
| `get_folder_stats` | Per-folder stats: last scan, last synced file |
| `get_errors` | Current system errors |
| `get_logs` | Recent log entries (filterable by timestamp) |
| `get_pending_devices` | Devices requesting to connect |
| `get_pending_folders` | Folders offered by remote devices |
| `browse_folder` | Browse files/directories within a synced folder |
| `health_check` | Quick up/down health check (no auth required) |

### Actions (8 tools)

| Tool | Description |
|------|-------------|
| `scan_folder` | Trigger folder rescan (full or subfolder) |
| `pause_device` | Pause syncing with a specific device |
| `resume_device` | Resume syncing with a specific device |
| `pause_all` | Pause all syncing |
| `resume_all` | Resume all syncing |
| `override_folder` | Force local state as authoritative (send-only folders) |
| `revert_folder` | Revert local changes to match remote (receive-only folders) |
| `clear_errors` | Clear system error log |

### Configuration (12 tools)

| Tool | Description |
|------|-------------|
| `add_folder` | Add a new shared folder |
| `update_folder` | Modify folder settings |
| `remove_folder` | Remove a shared folder (files on disk unchanged) |
| `add_device` | Add a new device by ID |
| `update_device` | Modify device settings |
| `remove_device` | Remove a device |
| `accept_device` | Accept a pending device connection |
| `reject_device` | Reject a pending device connection |
| `accept_folder` | Accept a pending folder share |
| `reject_folder` | Reject a pending folder share |
| `get_config` | Get full config or a specific section |
| `restart` | Restart the Syncthing service |

## Client Configuration

### Claude Desktop

```json
{
  "mcpServers": {
    "syncthing": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-remote", "http://your-host:8088/mcp"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add syncthing http://your-host:8088/mcp
```

### stdio mode

```json
{
  "mcpServers": {
    "syncthing": {
      "command": "uv",
      "args": ["--directory", "/path/to/syncthing-mcp", "run", "syncthing-mcp"],
      "env": {
        "SYNCTHING_URL": "http://localhost:8384",
        "SYNCTHING_API_KEY": "your-key",
        "TRANSPORT": "stdio"
      }
    }
  }
}
```

## Deployment (systemd)

```bash
sudo cp syncthing-mcp.service /etc/systemd/system/
sudo systemctl enable --now syncthing-mcp
```

## Development

```bash
uv sync --dev
uv run pytest tests/ -v
uv run ruff check .
uv run ruff format --check .
```

## License

MIT