vault-sync-mcp

A FastMCP server for bidirectional sync between a personal Obsidian vault and a shared team vault. Designed for teams where one person (the vault owner) maintains the source of truth and shares selected content with collaborators via a shared folder (Google Drive, Dropbox, etc.).

Tools

Tool	What it does
`vault_sync_status`	Show pending changes, stale files, and last sync time
`vault_sync_push`	Push eligible files from personal vault to team vault
`vault_sync_pull`	Pull changes from team vault back to personal vault
`vault_scope_check`	Check if a specific file is eligible for sync

Both push and pull default to dry_run: true — you always preview before executing.

Install

Open Claude Code, paste:

/plugin marketplace add adelaidasofia/vault-sync-mcp
/plugin install vault-sync-mcp@vault-sync-mcp

Then edit config.yaml to set your vault paths and sync rules:

personal_vault: ~/vault/
team_vault: ~/team-vault/

Restart Claude Code. Then ask:

"Show me vault sync status" "Push changes to team vault (dry run first)"

Legacy install

pip install fastmcp python-frontmatter pyyaml xxhash

Clone:

git clone https://github.com/adelaidasofia/vault-sync-mcp.git
cd vault-sync-mcp

Edit config.yaml to set your vault paths and sync rules:

personal_vault: ~/vault/
team_vault: ~/team-vault/

claude mcp add vault-sync -s user -- python3 /path/to/vault-sync-mcp/server.py

Restart Claude Code. Then ask:

"Show me vault sync status" "Push changes to team vault (dry run first)"

Configuration

Everything lives in config.yaml:

personal_vault: ~/vault/
team_vault: ~/team-vault/

no_sync:
  - "Journal/"
  - "Personal/"

sync_rules:
  - path: "Team/"
    direction: bidirectional

  - path: "CRM/"
    direction: personal_to_team
    filter:
      frontmatter_field: relationship
      frontmatter_values: [client, team, advisor]

Sync rule directions

bidirectional — changes flow both ways
personal_to_team — personal is source of truth, team gets updates
team_to_personal — team is source of truth, personal gets updates (useful for shared docs)

Blocking sync on a file

Add sync: false to any file's frontmatter to exclude it from all sync operations.

Environment variables

Variable	Default	Description
`VAULT_SYNC_PERSONAL`	from config.yaml	Personal vault root path
`VAULT_SYNC_TEAM`	from config.yaml	Team vault root path

Notes

Uses os.walk(followlinks=True) instead of Path.rglob() to correctly handle macOS symlinks (Google Drive, iCloud shortcuts)
Wikilinks are automatically rewritten to bare filenames during push ([[folder/Note]] becomes [[Note]])
Content hashing via xxhash for fast change detection
Conflict resolution: newer file wins; conflicts are logged and skipped

Related MCPs

Same author, same architecture pattern (FastMCP, draft+confirm on writes where applicable, vault auto-export, MIT):

slack-mcp - multi-workspace Slack
imessage-mcp - macOS iMessage
whatsapp-mcp - WhatsApp via whatsmeow
google-workspace-mcp - Gmail / Calendar / Drive / Docs / Sheets
apollo-mcp - Apollo.io CRM + sequences
substack-mcp - Substack writing + analytics
luma-mcp - lu.ma events
parse-mcp - markitdown / Docling / LlamaParse router
rescuetime-mcp - RescueTime productivity data
graph-query-mcp - vault knowledge graph queries
graph-autotagger-mcp - wikilink suggestions from the graph
investor-relations-mcp - seed-raise pipeline tracker

Telemetry

This plugin sends a single anonymous install signal to myceliumai.co the first time it loads in a Claude Code session on a given machine.

What is sent:

Plugin name (e.g. slack-mcp)
Plugin version (e.g. 0.1.0)

What is NOT sent:

No user identifiers, names, emails, tokens, or API keys
No file paths, message content, or anything from your work
No IP address is stored after dedup processing

Why: Helps the maintainer know which plugins people actually install, so attention goes to the ones that get used.

Opt out: Set the environment variable MYCELIUM_NO_PING=1 before launching Claude Code. The hook will skip the network call entirely. Already-pinged installs leave a sentinel at ~/.mycelium/onboarded-<plugin> — delete it if you want to reset state.

License

MIT

Built by Mycelium AI. Full install or team version at diazroa.com.

FastMCP server for bidirectional sync between personal and team Obsidian vaults