接入你的智能体
发布者自己的命令。不是 PlugMCP 端点。
用我们的密钥与日志托管一份副本。
npx -y @dinglebear/[email protected]Claude Code 没有针对本地命令的安装链接。复制下方命令并在终端中运行。
SYNAPSE_HOME=<value> SYNAPSE_HOSTS_CONFIG=<value> SYNAPSE_CONFIG_FILE=<value> SYNAPSE_RMCP_VERSION=<value> SYNAPSE_RMCP_REPO=<value> SYNAPSE_RMCP_RELEASE_BASE_URL=<value> RUST_LOG=<value> claude mcp add dinglebear-ai-synapse -- npx -y @dinglebear/synapse@1.0.0在终端中运行。
{ "mcpServers": { "dinglebear-ai-synapse": { "command": "npx", "args": [ "-y", "@dinglebear/[email protected]" ], "env": { "SYNAPSE_HOME": "<value>", "SYNAPSE_HOSTS_CONFIG": "<value>", "SYNAPSE_CONFIG_FILE": "<value>", "SYNAPSE_RMCP_VERSION": "<value>", "SYNAPSE_RMCP_REPO": "<value>", "SYNAPSE_RMCP_RELEASE_BASE_URL": "<value>", "RUST_LOG": "<value>" } } }}claude_desktop_config.json
远程 URL 还是本机命令？ 两种安装方式的区别
来自发布者
Host, Docker, Compose, SSH, logs, ZFS, and file operations over MCP and CLI.
Synapse is a full-parity Rust port of synapse-mcp, built with the rmcp framework.
The server exposes two MCP tools ( and ) plus equivalent CLI commands, covering all 59 production actions from the original TypeScript server.
Rust MCP and CLI server for local Synapse workflows: Docker/Compose control, host inspection, SSH, logs, ZFS, and safe file operations.
fluxscoutThe repository is synapse-rmcp, the Rust crate is synapse, the MCP server
identity is synapse, and the installed binary is synapse. The npm launcher
package is synapse-rmcp.
Across most of the RMCP family, naming follows
repo=<service>-rmcp, npm=<service>-rmcp, and CLI=r<service>. Synapse is an
exception because it is a Rust port of the older TypeScript synapse-mcp
project and keeps the operator-facing synapse binary.
Synapse provides local Docker, Compose, host, SSH, log, ZFS, and file-operation workflows through two MCP tools and the equivalent CLI:
flux manages Docker infrastructure, containers, Compose projects, and host
inspection.scout handles SSH/local host inspection, safe file reads, allowlisted
command execution, bounded descriptor-confined file transfer, ZFS introspection,
and log retrieval.Not for: arbitrary shell access, unaudited remote mutation, or bypassing host SSH trust. Destructive Docker/Compose/exec/file-transfer actions require explicit host targets and confirmation policy.
MCP callers never provide credentials, tokens, keys, or secrets as action arguments. Tokens, OAuth settings, host topology, SSH trust, and allowlists live in server-side configuration or the local SSH environment.
Use the npm launcher for stdio MCP or CLI access without a manual binary install:
npx -y @dinglebear/synapse --help
npx -y @dinglebear/synapse mcp
For a permanent command:
npm i -g @dinglebear/synapse
synapse --version
The npm package downloads the synapse binary from GitHub Releases during
postinstall, keeping the release tag aligned with
packages/synapse-rmcp/package.json.
From source:
cargo build --release
The production image includes Python 3 plus the official Docker CLI/Compose
plugin because Scout's remote descriptor wrappers and Flux Compose operations
invoke those runtime tools. The image does not contain a Docker daemon; Flux
uses the mounted socket or SSH-forwarded remote socket. Persistent appdata lives
at ~/.synapse on the host and /data in the container.
The first-screen 30-second path is:
npx -y @dinglebear/synapse mcp
Then configure an MCP client with stdio:
{
"mcpServers": {
"synapse": {
"command": "npx",
"args": ["-y", "synapse-rmcp", "mcp"]
}
}
}
Start with a read-only call:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "scout",
"arguments": {
"action": "nodes"
}
}
}
stdio is preferred for local MCP clients:
{
"mcpServers": {
"synapse": {
"command": "synapse",
"args": ["mcp"]
}
}
}
Streamable HTTP uses /mcp on the configured host and port:
{
"mcpServers": {
"synapse": {
"url": "http://127.0.0.1:40080/mcp",
"headers": {
"Authorization": "Bearer ${SYNAPSE_MCP_TOKEN}"
}
}
}
}
plugins/synapse/ ships Claude Code, Codex, and Gemini CLI manifests that all
point at the same HTTP MCP endpoint and the same shared skill.
These packages contain no lifecycle hooks. Connecting to a server that is
already running needs no setup — the manifests substitute your server_url and
api_token directly. If this machine also runs the server, bootstrap it once
by hand:
synapse setup install # put/refresh the binary on PATH
synapse setup plugin-hook # check, then repair on blocking failures
synapse setup plugin-hook --no-repair # audit only; never mutates appdata
Export the relevant SYNAPSE_* variables (or write them to ~/.synapse/.env)
first; plugins/README.md maps each plugin option to its variable. Re-run
synapse setup install after a plugin update.
Synapse exposes two MCP tools:
flux: Docker daemon, container, host, and Compose operations.scout: SSH/local host inspection, filesystem reads, allowlisted exec,
multi-host emit, file beam, ZFS, and logs.Both tools use an action-dispatched JSON shape:
{"name":"flux","arguments":{"action":"docker","subaction":"info"}}
{"name":"scout","arguments":{"action":"nodes"}}
The detailed action tables below are curated README reference material. The generated runtime MCP schema and the Rust action definitions are the source of truth for the live tool contract.
Common commands:
synapse flux docker info
synapse flux container list
synapse flux compose list --host myhost
synapse scout nodes
synapse scout exec --host myhost --command hostname
synapse scout zfs pools --host myhost
synapse scout logs journal --host myhost --unit docker
Mounted HTTP supports bearer and Google OAuth modes. Loopback stdio/local dev can run without mounted HTTP auth. Important variables:
SYNAPSE_MCP_HOST=127.0.0.1
SYNAPSE_MCP_PORT=40080
SYNAPSE_MCP_TOKEN=change-me
SYNAPSE_MCP_AUTH_MODE=bearer
See Configuration and docs/CONFIG.md for the full auth
matrix.
Synapse separates read and write scopes (synapse:read, synapse:write) and
uses confirmation gates for destructive operations. SYNAPSE_MCP_ALLOW_DESTRUCTIVE
can skip prompts only in loopback-safe contexts. Host protocol is authoritative
and defaults to SSH when omitted; local execution requires the explicit built-in
local host or protocol: "local". SSH host trust is delegated to OpenSSH
known-hosts behavior, and command execution uses execvp/argv semantics without
shell interpolation. scout beam enforces both endpoints' configured read roots,
blocks sensitive and symlinked paths, and caps each transfer at 64 MiB.
scout exec and scout emit accept only these 18 typed commands
(ALLOWED_READ_COMMANDS in src/synapse/command_policy.rs):
cat, head, tail, grep, rg, ls, tree, wc, uniq, diff, stat,
file, du, df, pwd, hostname, uptime, whoami
git is deliberately excluded, as are shells, interpreters, network clients, and
mutating tools (EXEC_DENYLIST). There is no find or sort in the allowlist —
use the dedicated scout find action for filesystem search. Per-host custom
commands may be enabled via execAllowlist, but receive a zero-argument policy
until a typed argument policy is registered.
The source of truth for release identity is the version shared by Cargo.toml,
.release-please-manifest.json, packages/synapse-rmcp/package.json, release
artifacts, and server.json.
Distribution/version invariants:
synapse.server.json must point at ghcr.io/dinglebear-ai/synapse:<version>.just validate-plugin # plugin manifests, MCP config, monitors, skills
npm --prefix packages/synapse-rmcp run check
cargo fmt --check
cargo check
cargo test
git diff --check
For a persistent mounted HTTP server:
SYNAPSE_MCP_HOST=0.0.0.0 \
SYNAPSE_MCP_PORT=40080 \
SYNAPSE_MCP_TOKEN=change-me \
synapse serve
Use bearer or OAuth before exposing the endpoint beyond loopback. Production
Docker/Compose notes live in docs/DEPLOYMENT.md and docs/DOCKER.md when
present; local operator usage can stay on stdio.
401 or 403 from /mcp: check bearer/OAuth settings and gateway headers.SYNAPSE_HOSTS_CONFIG, SYNAPSE_CONFIG_FILE, and
~/.ssh/config.flux — Docker infrastructure managementflux docker — Docker daemon operations (9 actions)flux container — Container lifecycle + inspection (14 actions)flux host — Host inspection (9 actions)flux compose — Docker Compose project management (10 actions)flux help — Auto-generated flux docsscout — SSH/local host inspectionscout zfs — ZFS introspection (3 subactions)scout logs — Log retrieval (4 subactions)scout help — Auto-generated scout docssynapse achieves action-level parity with synapse-mcp — all 59
production actions from synapse-mcp/docs/INVENTORY.md are implemented. However,
the following features from the original TypeScript server are not yet ported:
SYNAPSE_MCP_HOST=127.0.0.1
SYNAPSE_MCP_PORT=40080
SYNAPSE_MCP_TOKEN=change-me
Key environment variables:
See .env.example for the full list of variables, docs/CONFIG.md for
configuration details, and docs/SECURITY.md for transport, path, transfer,
container, and CI runner trust boundaries.
# Start MCP server (stdio transport)
cargo run -- mcp
# Start HTTP server
cargo run -- serve
# CLI examples
cargo run -- flux docker info
cargo run -- flux container list
cargo run -- flux compose list --host myhost
cargo run -- scout nodes
cargo run -- scout exec --host myhost --command hostname
cargo run -- scout zfs pools --host myhost
cargo run -- scout logs journal --host myhost --unit docker
MCP examples:
{"name":"flux","arguments":{"action":"docker","subaction":"info"}}
{"name":"flux","arguments":{"action":"container","subaction":"list","state":"running"}}
{"name":"flux","arguments":{"action":"compose","subaction":"status","host":"myhost","project":"mystack"}}
{"name":"scout","arguments":{"action":"nodes"}}
{"name":"scout","arguments":{"action":"exec","host":"myhost","command":"hostname"}}
{"name":"scout","arguments":{"action":"zfs","subaction":"pools","host":"myhost"}}
{"name":"scout","arguments":{"action":"logs","subaction":"journal","host":"myhost","unit":"docker"}}
FluxService (src/flux_service/) Docker/container/compose/host ops
ScoutService (src/scout_service/) SSH/exec/fs/zfs/logs ops
↓ via SynapseService facade (src/app.rs)
MCP shims (src/mcp/tools.rs) tool args → service → Value
CLI shim (src/cli.rs) argv → service → stdout
REST layer (src/api.rs) POST /v1/synapse → service → JSON
cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release
just dev # serve with no auth (loopback, dev mode)
just test # cargo test
just lint # clippy
just fmt # cargo fmt
Useful docs:
docs/API.md for full tool contractsdocs/CONFIG.md for environment and authdocs/QUICKSTART.md for local smoke testsplugins/synapse/skills/synapse/SKILL.md for agent usage guidancetests/parity.rs for automated parity verification against synapse-mcp INVENTORYThis README is curated for first-run orientation and high-level action discovery. Source-of-truth docs and code are split as follows:
docs/API.md for the curated action contract reference.docs/MCP_SCHEMA.md for MCP schema shape and drift expectations.docs/CONFIG.md for environment and auth policy.docs/QUICKSTART.md for local smoke tests.docs/PLUGINS.md and plugins/synapse/skills/synapse/SKILL.md for agent
and marketplace usage.docs/generated/openapi.json for generated OpenAPI output.src/flux_service/, src/scout_service/, and src/mcp/ for runtime source
of truth.runifi - UniFi controller REST API bridge.rtailscale - Tailscale API bridge for devices, users, and tailnet operations.unraid / runraid - Unraid GraphQL bridge for NAS and server management.rapprise - Apprise notification fan-out bridge for many delivery backends.rgotify - Gotify push notification bridge for sends, messages, apps, and clients.rarcane - Arcane Docker management bridge for containers and related resources.yarr - Media-stack bridge for Sonarr, Radarr, Prowlarr, Plex, and related services.rytdl - Media download and metadata workflow server.cortex - Syslog and homelab log aggregation MCP server.axon - RAG, crawl, scrape, extract, and semantic search project.labby - Homelab control plane and Labby gateway project.lumen - Local semantic code search MCP server.nugs - Project/package management helper for local agent workflows.agentcast - Agent transcript and activity publishing project.soma - RMCP scaffold/runtime template for new provider-backed servers.Original Dinglebear-authored portions of this project are licensed under AGPL-3.0-only. Separate commercial licensing is available for organizations that need terms outside the AGPL. Third-party material remains under its original license. See LICENSING.md.
Rust MCP and CLI server for local Synapse workflows: Docker/Compose control, host inspection, SSH, logs, ZFS, and safe file operations.
{ "mcpServers": { "dinglebear-ai-synapse": { "command": "npx", "args": [ "-y", "@dinglebear/[email protected]" ], "env": { "SYNAPSE_HOME": "<value>", "SYNAPSE_HOSTS_CONFIG": "<value>", "SYNAPSE_CONFIG_FILE": "<value>", "SYNAPSE_RMCP_VERSION": "<value>", "SYNAPSE_RMCP_REPO": "<value>", "SYNAPSE_RMCP_RELEASE_BASE_URL": "<value>", "RUST_LOG": "<value>" } } }}工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式，而不是 PlugMCP 代理。
发布者列出了以下环境变量：SYNAPSE_HOME, SYNAPSE_HOSTS_CONFIG, SYNAPSE_CONFIG_FILE, SYNAPSE_RMCP_VERSION, SYNAPSE_RMCP_REPO, SYNAPSE_RMCP_RELEASE_BASE_URL, RUST_LOG。
Synapse 通过 stdio 在本地运行。
上次检查时间：2026-10-28。 Rust MCP and CLI server for local Synapse workflows: Docker/Compose control, host inspection, SSH, logs, ZFS, and safe file operations.