fast-note-sync-service

简体中文 / English / 日本語 / 한국어 / 繁體中文

If you have any questions, please create an issue or join our Telegram group for help: https://t.me/obsidian_users

For users in Mainland China, it is recommended to use the Tencent cnb.cool mirror repository: https://cnb.cool/haierkeys/fast-note-sync-service

Fast Note Sync Service

High-performance, low-latency note synchronization, online management, and remote REST API service platform
Built with Golang + Websocket + React

Data provisioning requires integration with the client plugin: Obsidian Fast Note Sync Plugin

Key Features

• ** Native MCP (Model Context Protocol) Support**:

  • FNS can be integrated as an MCP server into compatible AI clients such as Cherry Studio and Cursor. This enables the AI to read and write your personal notes and attachments, with all changes synchronized across all clients in real-time.

• ** REST API Support**:

  • Provides standard REST API interfaces to support programmatic CRUD operations on Obsidian notes (e.g., via automation scripts or AI assistant integrations).
  • For details, please refer to the RESTful API Documentation or OpenAPI Documentation.

• ** Web Admin Panel**:

  • Built-in modern administration interface to easily create users, generate plugin configurations, and manage vaults and note content.
  • Supports WebGUI OIDC login. See the OIDC login runbook.

• ** Multi-Device Note Synchronization**:

  • Supports automatic creation of Vaults.
  • Supports note management (CRUD), with millisecond-level real-time change distribution to all online devices.

• ️ Attachment Sync Support:

  • Perfectly supports synchronization of non-note files such as images.
  • Supports chunked upload and download for large attachments, with configurable chunk sizes to improve sync efficiency.

• ⚙️ Configuration Sync:

  • Supports synchronization of .obsidian configuration files.
  • Supports PDF reading progress synchronization.

• ** Note History**:

  • View historical revision versions of each note via the Web UI or client plugin.
  • (Requires server v1.2+)

• ️ Trash Bin:

  • Deleted notes automatically go to the trash bin.
  • Supports restoring notes from the trash. (Attachment restoration feature will be added sequentially in the future.)

• ** Offline Synchronization Strategy**:

  • Supports automatic merging of offline note edits. (Requires client plugin configuration)
  • Offline deletions are automatically resolved (re-synced or deleted) upon reconnection. (Requires client plugin configuration)

• ** Sharing Feature**:

  • Easily share or unshare notes.
  • Automatically parses images, audio, video, and other attachments referenced in shared notes.
  • Provides sharing access statistics.
  • Allows password protection for shared notes.
  • Supports generating short URLs for shared notes.

• ** Folder Sync**:

  • Supports folder synchronization for creation, renaming, moving, and deletion.

• ** Git Automation**:

  • Automatically updates and pushes changes to a remote Git repository when notes or attachments change.
  • Automatically releases system memory after tasks complete.

• ☁️ Multi-Storage Backup & One-way Mirror Sync:

  • Adapts to S3, OSS, R2, WebDAV, local filesystem, and other storage protocols.
  • Supports scheduled full or incremental ZIP archive backups.
  • Supports one-way mirror synchronization of Vault resources to remote storage.
  • Automatically cleans up expired backups with custom retention days.

• ️ Multi-Database Support:

  • Native support for mainstream databases including SQLite, MySQL, and PostgreSQL, meeting deployment needs from individuals to teams.

☕ Sponsorship and Support

• If you find this plugin useful and want to support its ongoing development, please support me in the following ways:

  Ko-fi Outside China		WeChat Pay China
  	or

  • Sponsor List:
    • Support.en.md
    • Support.en.md (cnb.cool mirror repository)

⏱️ Changelog

• ♨️ Click to View Changelog

️ Roadmap

• Add support for WebSocket Protobuf transfer format to enhance synchronization efficiency.
• Isolate and optimize the existing authorization mechanism to improve overall security.
• Add real-time note updates to the Web UI.
• Add peer-to-peer message transfer between clients (non-notes & attachments, similar to LocalSend; client-side storage is not supported, but server-side is).
• Improve various help documentations.
• Provide support for more intranet penetration (relay gateway) options.
• Quick deployment plan:
  • Deploy the FNS server by simply providing the server address (public IP) and account credentials.
• Optimize the existing offline note merging scheme and introduce conflict resolution mechanisms.

We are continuously improving, and here is our future development roadmap:

If you have suggestions for improvement or new ideas, feel free to share them with us by submitting an issue — we will carefully evaluate and adopt suitable ones.

Quick Deployment

We provide multiple installation methods. We highly recommend using the One-click Script or Docker.

Method 1: One-click Script (Recommended)

Automatically detects the system environment and completes the installation and service registration.

bash <(curl -fsSL https://raw.githubusercontent.com/haierkeys/fast-note-sync-service/master/scripts/quest_install.sh)

For users in China, you can use the Tencent cnb.cool mirror source:

bash <(curl -fsSL https://cnb.cool/haierkeys/fast-note-sync-service/-/git/raw/master/scripts/quest_install.sh) --cnb

Main Script Behaviors:

• Automatically downloads the Release binary adapted to the current system.
• Installs to /opt/fast-note by default and creates a global shortcut command fns in /usr/local/bin/fns.
• Configures and starts Systemd (Linux) or Launchd (macOS) services to enable startup on boot.
• Management commands: fns [install|uninstall|start|stop|status|update|menu]
• Interactive menu: Run fns directly to enter the interactive menu, supporting install/upgrade, service control, startup configuration, and switching between GitHub and CNB mirrors.

Method 2: Docker Deployment

Docker Run

# 1. Pull Image
docker pull haierkeys/fast-note-sync-service:latest

# 2. Start Container
docker run -tid --name fast-note-sync-service \
    -p 9000:9000 \
    -v /data/fast-note-sync/storage/:/fast-note-sync/storage/ \
    -v /data/fast-note-sync/config/:/fast-note-sync/config/ \
    haierkeys/fast-note-sync-service:latest

Docker Compose

Create the docker-compose.yaml file:

version: '3'
services:
  fast-note-sync-service:
    image: haierkeys/fast-note-sync-service:latest
    container_name: fast-note-sync-service
    restart: always
    ports:
      - "9000:9000"  # RESTful API & WebSocket port (where /api/user/sync is the WebSocket interface address)
    volumes:
      - ./storage:/fast-note-sync/storage  # Data storage
      - ./config:/fast-note-sync/config    # Configuration files

Start the service:

docker compose up -d

Method 3: Manual Binary Installation

Download the latest version for your system from Releases, extract it, and run:

./fast-note-sync-service run -c config/config.yaml

User Guide

1. Access Admin Panel: Open http://{Server_IP}:9000 in your browser.
2. Initial Setup: Register an account on your first visit. (To disable registration, set user.register-is-enable: false in the configuration file)
3. Configure Client: Log in to the admin panel and click "Copy API Config".
4. Connect to Obsidian: Open the Obsidian plugin settings page and paste the configuration information you just copied.

⚙️ Configuration Description

The default configuration file is config.yaml. The application automatically searches in the root directory or the config/ directory.

View the complete configuration example: config/config.yaml

Nginx Reverse Proxy Example

View the complete configuration example: https-nginx-example.conf

MCP (Model Context Protocol) Support

FNS now natively supports MCP (Model Context Protocol) and provides both SSE and StreamableHTTP transport protocols.

You can integrate FNS as an MCP server directly into compatible AI clients like Cherry Studio, Cursor, Claude Code, and hermes-agent. Once integrated, the AI will gain the ability to read and write your personal notes and attachments. In addition, all modifications made via MCP will be synchronized to your client devices in real-time via WebSocket.

For OAuth-protected MCP deployments with Stytch, see docs/runbook/mcp-oauth-stytch.md (简体中文, 繁體中文).

Common Request Header Parameters

The following request headers are supported regardless of the transport mode used:

• Authorization Header: Authorization: Bearer <Your API Token> (obtained from the Copy API Config option in the WebGUI)
• Optional Header: X-Default-Vault-Name: <Vault Name> (specifies the default Vault name for MCP operations if no vault parameter is provided during a tool call)
• Optional Header: X-Client: <Client Type> (the type of client connecting to MCP, e.g., Cherry Studio, OpenClaw)
• Optional Header: X-Client-Version: <Client Version> (the version of the client connecting, e.g., 1.1)
• Optional Header: X-Client-Name: <Client Name> (the name of the client connecting, e.g., Mac)

Integration Config: StreamableHTTP Mode (Recommended)

StreamableHTTP is the standard transport protocol in the MCP ecosystem. A single endpoint can handle all requests, making it more firewall-friendly. It is natively supported by newer MCP clients (such as Claude Code and hermes-agent).

• Interface Address: http://<Your_Server_IP_or_Domain>:<Port>/api/mcp
• Request Method: `P