Hermes Obsidian Drive MCP

Connect Hermes Agent directly to the Google Drive vault synced by Richard Xiong's Obsidian Google Drive Sync plugin. This project includes both:

• a focused MCP connector for reading and safely editing Markdown notes; and

• a Hermes skill that teaches the agent how to use those tools safely.

It does not require Obsidian on the server, rclone, a second vault copy, or changes to Richard's plugin.

Obsidian on PC ─ Richard's plugin ─┐
                                  ├─ Google Drive ─ Obsidian Drive MCP ─ Hermes
Obsidian on phone ─ Richard's plugin ┘

Quick start: Windows

Requirements: Node.js 22 or newer, a Google account already syncing the vault, and a Google Cloud OAuth Desktop app client.

1. In Google Cloud Console, create/select a project, enable the Google Drive API, then create OAuth credentials with application type Desktop app. Keep the client ID and secret private.

2. In PowerShell, open this project folder and run:

npm install
npm run build
npm run setup
npm run doctor

Setup asks for your OAuth client ID and secret (secret input is hidden in an interactive terminal), timezone, and vault. It prints an authorization URL; open it in a browser, sign in with the same Google account Richard's plugin uses, and approve Drive access. If more than one compatible vault is found, choose the intended one—setup will not guess.

The default timezone is UTC. Enter an IANA name such as Europe/London or a fixed UTC offset such as +4 or -05:30. Configuration and tokens are saved locally; after setup, the MCP does not need Google credentials in environment variables.

Optional local smoke test:

npx @modelcontextprotocol/inspector node dist/src/index.js

Related MCP server: Obsidian MCP

Install the connector in Hermes

Build and set up the connector first. Then, on the machine that runs Hermes, add it with Hermes' MCP command:

hermes mcp add obsidian --command node --args /path/to/hermes-obsidian-drive-mcp/dist/src/index.js
hermes mcp test obsidian
hermes mcp list

For example, if installed at /opt/hermes-obsidian-drive-mcp:

hermes mcp add obsidian --command node --args /opt/hermes-obsidian-drive-mcp/dist/src/index.js
hermes mcp test obsidian

Hermes may ask which tools to enable; choose all 12 or select your preferred set. Start a new Hermes session after registration so it loads the connector tools. Hermes' MCP support and CLI are documented in the Hermes MCP guide.

If using YAML instead of the CLI, merge the contents of hermes-config.example.yaml into the existing mcp_servers: map. Do not add a second nested mcp_servers: key.

Install the Hermes skill

The skill is in skills/obsidian-drive-mcp/SKILL.md. It instructs Hermes to search before opening many notes, carry versions into writes, recover safely from conflicts, prefer patches/appends, and respect deletion and sync limitations.

After this repository is published as OWNER/REPO, install the skill with Hermes' skill tap:

hermes skills tap add OWNER/REPO
hermes skills install OWNER/REPO/obsidian-drive-mcp
hermes skills list

Start a new session after installing it. See the Hermes skills guide for tap and skill-management details. You can also copy the skill directory to ~/.hermes/skills/obsidian-drive-mcp/.

VPS deployment

Use Node.js 22+ on Linux. The recommended flow is to authorize on the VPS through an SSH tunnel, avoiding manual transfer of refresh tokens:

1. Copy/clone this project to the VPS (example destination: /opt/hermes-obsidian-drive-mcp).

2. In one terminal on your PC, keep this SSH tunnel open:

ssh -L 53682:127.0.0.1:53682 USER@YOUR_VPS

3. In another VPS session:

cd /opt/hermes-obsidian-drive-mcp
npm ci
npm run build
npm run setup
npm run doctor

4. Open the authorization URL printed by setup in your PC browser. The tunnel forwards Google's callback back to the VPS.

5. Register and test the MCP as shown above.

Configuration and OAuth tokens are stored under ~/.config/hermes-obsidian-drive-mcp/ on Linux. Keep these files private; restrict them to the Hermes account (chmod 700 ~/.config/hermes-obsidian-drive-mcp && chmod 600 ~/.config/hermes-obsidian-drive-mcp/config.json ~/.config/hermes-obsidian-drive-mcp/token.json). If you instead copy an already-authorized config from another machine, transfer it only over a secure channel and apply the same permissions. The config contains the OAuth client secret and the token file contains a refresh token.

Google OAuth apps left in Testing status may have refresh tokens that expire after seven days. For a persistent deployment, configure the consent screen and publishing status appropriate for your Google account.

What the MCP provides

• vault_context: vault identity, note count, UTC/local time, and recent activity.

• list_notes, search_notes, read_note, recent_changes: discover and read notes.

• create_note, patch_note, append_note, write_note, move_note: safe note operations with optimistic concurrency for edits.

• note_history: inspect Drive revisions.

• delete_note: registered but disabled by default; when explicitly enabled, it moves notes to Drive trash.

On a conflict, reread the note and reconcile newer phone/PC edits before retrying. Never blindly overwrite a newer version. Writes go to Google Drive immediately; visibility on phone and PC still depends on when Richard's plugin next pulls changes. Do not assume an open Obsidian device has already refreshed.

Configuration and safety

Setup persists OAuth credentials, selected vault, timezone, and delete policy in a cross-platform config file. Environment variables override persisted config when needed:

GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, OBSIDIAN_VAULT_NAME, OBSIDIAN_TIMEZONE, and OBSIDIAN_ALLOW_DELETE.

Path overrides: OBSIDIAN_MCP_CONFIG_DIR, OBSIDIAN_MCP_CONFIG_FILE, and OBSIDIAN_MCP_TOKEN_FILE. Defaults use the OS config directory (normally ~/.config/hermes-obsidian-drive-mcp/ on Linux and %APPDATA%/hermes-obsidian-drive-mcp/ on Windows; an existing legacy ~/.config location is preserved).

npm run doctor is strictly read-only. It checks config, token refresh, Drive access, account, vault selection, timezone, and Richard-compatible metadata without writing, moving, or deleting Drive objects. Deletes are off by default.

Development and tests

npm ci
npm run build
npm test

The unit tests are offline and do not touch a real vault. Live Drive round trips require explicit opt-in:

OBSIDIAN_INTEGRATION_TEST=1 npm run test:integration

PowerShell:

$env:OBSIDIAN_INTEGRATION_TEST = '1'
npm run test:integration
Remove-Item Env:OBSIDIAN_INTEGRATION_TEST

The integration test creates, patches, appends to, and moves a unique temporary note. If deletion is disabled, it leaves the note in Drive and prints its path for manual cleanup; if deletion is enabled, it moves that test note to Drive trash.

Richard plugin compatibility

This is a Drive-side client, not a generic Drive filesystem. It identifies vault roots and scopes files using the plugin's custom Drive properties, reconstructs Unicode-safe path chunks, creates compatible Drive folders, and preserves existing Drive file IDs on updates. The implementation has been checked against Richard Xiong's drive helper and push helper.

The MCP filters Obsidian/plugin configuration files and does not edit them. It does not promise immediate inbound sync to phone/PC; Richard's plugin controls pull timing.