FastMCP server for bidirectional sync between personal and team Obsidian vaults
FastMCP server for bidirectional sync between personal and team Obsidian vaults.
Open source Open in the app JSON README (API)
About
FastMCP server for bidirectional sync between personal and team Obsidian vaults.
Details
- Kind
- MCP servers
- Topic
- Productivity
- Publisher
- adelaidasofia
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Last push
- 2026-08-23T01:59:01Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:22
- Updated
- 2026-08-29 03:02:22
- Origin id
io.github.adelaidasofia/vault-sync-mcp
README
# vault-sync-mcp
<!-- mycelium-badges:start -->
<p>
<a href="https://github.com/adelaidasofia/vault-sync-mcp/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/adelaidasofia/vault-sync-mcp?color=blue"></a>
<a href="https://github.com/adelaidasofia/vault-sync-mcp/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/adelaidasofia/vault-sync-mcp?color=eab308"></a>
<a href="https://github.com/adelaidasofia/vault-sync-mcp/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/adelaidasofia/vault-sync-mcp"></a>
<a href="https://github.com/adelaidasofia/vault-sync-mcp/issues"><img alt="Open issues" src="https://img.shields.io/github/issues/adelaidasofia/vault-sync-mcp"></a>
<a href="https://pypi.org/project/adelaidasofia-vault-sync-mcp/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/adelaidasofia-vault-sync-mcp?color=blue&label=pypi"></a>
<a href="https://pypi.org/project/adelaidasofia-vault-sync-mcp/"><img alt="PyPI downloads" src="https://img.shields.io/pypi/dm/adelaidasofia-vault-sync-mcp?color=blue&label=downloads"></a>
<a href="https://myceliumai.co"><img alt="Built by Mycelium AI" src="https://img.shields.io/badge/built_by-Mycelium_AI-15B89A"></a>
</p>
<!-- mycelium-badges:end -->
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:
```yaml
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)"
<details><summary>Legacy install</summary>
```bash
pip install fastmcp python-frontmatter pyyaml xxhash
```
1. Clone:
```bash
git clone https://github.com/adelaidasofia/vault-sync-mcp.git
cd vault-sync-mcp
```
2. Edit `config.yaml` to set your vault paths and sync rules:
```yaml
personal_vault: ~/vault/
team_vault: ~/team-vault/
```
3. Register with Claude Code:
```bash
claude mcp add vault-sync -s user -- python3 /path/to/vault-sync-mcp/server.py
```
4. Restart Claude Code. Then ask:
> "Show me vault sync status"
> "Push changes to team vault (dry run first)"
</details>
## Configuration
Everything lives in `config.yaml`:
```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](https://github.com/adelaidasofia/slack-mcp) - multi-workspace Slack
- [imessage-mcp](https://github.com/adelaidasofia/imessage-mcp) - macOS iMessage
- [whatsapp-mcp](https://github.com/adelaidasofia/whatsapp-mcp) - WhatsApp via whatsmeow
- [google-workspace-mcp](https://github.com/adelaidasofia/google-workspace-mcp) - Gmail / Calendar / Drive / Docs / Sheets
- [apollo-mcp](https://github.com/adelaidasofia/apollo-mcp) - Apollo.io CRM + sequences
- [substack-mcp](https://github.com/adelaidasofia/substack-mcp) - Substack writing + analytics
- [luma-mcp](https://github.com/adelaidasofia/luma-mcp) - lu.ma events
- [parse-mcp](https://github.com/adelaidasofia/parse-mcp) - markitdown / Docling / LlamaParse router
- [rescuetime-mcp](https://github.com/adelaidasofia/rescuetime-mcp) - RescueTime productivity data
- [graph-query-mcp](https://github.com/adelaidasofia/graph-query-mcp) - vault knowledge graph queries
- [graph-autotagger-mcp](https://github.com/adelaidasofia/graph-autotagger-mcp) - wikilink suggestions from the graph
- [investor-relations-mcp](https://github.com/adelaidasofia/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](https://myceliumai.co). Full install or team version at [diazroa.com](https://diazroa.com).