Obsidian Workbench

Obsidian Workbench is a local-first TypeScript suite that gives MCP clients guarded access to authorized Obsidian vaults. It includes an MCP server, a single-file MCP App, shared contracts, a filesystem vault adapter, Codex skills, an Obsidian companion plugin, and remote-gateway integration boundaries.

The default local configuration is read-only. Write tools use explicit permission scopes, content revisions, idempotency keys, dry-run diffs, and short-lived confirmation tokens for high-risk mutations. Note content is returned as untrusted data and cannot grant permissions or authorize a write.

Release status: The local suite is implemented and tested. The remote bridge is an integration library, not a deployable hosted service: production authentication, durable metadata storage, account lifecycle, event consumption, legal policies, and production brand assets remain release blockers. See Current limitations and the release checklist.

Components

Component	Package/path	Responsibility
MCP server	packages/mcp-server	Registers the explicit tool catalog, serves STDIO or loopback Streamable HTTP, and embeds the MCP App resource.
MCP App	packages/mcp-app	Browsing, note editing, capture, tasks, maintenance reporting, diff review, and confirmation through a typed bridge.
Vault core	packages/vault-core	Filesystem adapter, Markdown semantics, path policy, search, revisions, idempotency, mutation plans, and confirmations.
Shared	packages/shared	Zod schemas, errors, permission scopes, and companion protocol contracts.
Companion	packages/obsidian-plugin	Permission-scoped Obsidian API adapter, outbound gateway connection, pairing, events, and local audit log.
Remote gateway	packages/remote-gateway	Authentication/persistence interfaces, pairing, scoped credentials, WebSocket sessions, replay controls, and request routing.
Skills	skills	Capture, research synthesis, daily review, note refactor, and vault maintenance workflows.

Detailed flows and trust boundaries are in Architecture. Every registered MCP tool is documented in the Tool catalog.

Requirements

• Node.js 22 or newer. Release CI uses Node.js 24.
• pnpm 10.33.2, as declared by packageManager.
• For the preserved Python prototype only: Python 3.12 and uv.
• Obsidian 1.5.0 or newer for the companion plugin.

Fresh Clone

Install the TypeScript workspace and the preserved Python environment:

pnpm install --frozen-lockfile
uv sync --all-groups --locked

Build all TypeScript packages:

pnpm build

The MCP App build emits packages/mcp-app/dist/index.html. The companion build emits packages/obsidian-plugin/main.js.

Test Vault

Use a disposable vault containing no sensitive notes. Do not initially point development clients at a primary vault.

Create a directory outside the repository or an ignored local directory, add a few Markdown files, and set one of these configurations:

• OBSIDIAN_VAULT_PATH: one filesystem vault; defaults to ID local-vault and read-only scopes vault.metadata.read, notes.read, and tasks.read.
• OBSIDIAN_VAULTS_JSON: an array of vault definitions with vaultId, rootPath, optional name, allowedRoots, excludedRoots, scopes, and partial conventions.

PowerShell read-only example:

$env:OBSIDIAN_VAULT_PATH = ".\path\to\test-vault"
$env:OBSIDIAN_VAULT_ID = "workbench-test"
$env:OBSIDIAN_VAULT_NAME = "Workbench Test Vault"

Writes must be granted explicitly. This development-only example allows note and task mutations while retaining folder policy:

$env:OBSIDIAN_VAULTS_JSON = '[{"vaultId":"workbench-test","rootPath":"./path/to/test-vault","name":"Workbench Test Vault","allowedRoots":["Inbox","Projects","Daily"],"excludedRoots":["Private"],"scopes":["vault.metadata.read","notes.read","notes.create","notes.update","notes.move","notes.trash","tasks.read","tasks.create","tasks.update"]}]'

.obsidian/ remains blocked. Relative examples assume the server starts with the repository root as its working directory. See Local development for test-vault setup and troubleshooting.

Local MCP Server

STDIO

STDIO is the default transport:

pnpm --filter @obsidian-workbench/mcp-server start

config/mcp.local.example.json is a secret-free MCP client template. It assumes pnpm build has completed and that the MCP process starts from this repository root. If a client requires absolute paths, put those paths in the client's untracked user configuration, never in a committed example.

Streamable HTTP

The HTTP transport has no application authentication and must remain loopback-only for local development:

$env:MCP_TRANSPORT = "http"
$env:MCP_HOST = "127.0.0.1"
$env:PORT = "8000"
pnpm --filter @obsidian-workbench/mcp-server start

• MCP endpoint: http://127.0.0.1:8000/mcp
• Health endpoint: http://127.0.0.1:8000/health
• Optional MCP_ALLOWED_HOSTS: comma-separated host allowlist.

Do not bind this server to a LAN or public interface. Use the authenticated remote architecture instead.

MCP App

Build the single-file app before starting the MCP server:

pnpm --filter @obsidian-workbench/mcp-app build
pnpm --filter @obsidian-workbench/mcp-server build

The server registers ui://obsidian-workbench/index.html with no external connect or resource domains. Hosts that support MCP Apps can open it from obsidian.list_vaults. MCP_APP_HTML_PATH can override the built HTML location for development.

config/mcp-app.example.json records the release resource metadata and points to the local MCP example. It is a repository deployment descriptor, not a portable client standard; runtime registration in packages/mcp-server/src/app/workbench-app.ts is authoritative.

The app never auto-saves. Its write path is edit, dry-run, inspect diff, confirm when required, then apply. The app-only obsidian.ui.confirm_mutation tool binds a short-lived token to the exact mutation plan.

Companion Installation

Build the plugin and install its three deployables into a development vault:

pnpm --filter @obsidian-workbench/obsidian-plugin build

1. Create <test-vault>/.obsidian/plugins/obsidian-workbench/.
2. Copy packages/obsidian-plugin/main.js, manifest.json, and styles.css into it.
3. In Obsidian, enable Community plugins, then enable Obsidian Workbench Companion.
4. Configure allowed/excluded roots and the minimum required scopes before pairing.
5. Enter the secure wss:// gateway URL and a one-time pairing code.

Pairing stores separate device-identity and vault-authorization credentials in Obsidian plugin data. The default lifetimes are 90 days and 30 days respectively; if either expires, the plugin refuses to connect and the vault must be paired again. There is no refresh flow. Review the companion README before using real vaults.

Remote Bridge

The implemented remote flow is:

authenticated MCP host -> RemoteVaultAdapter -> RequestRoutingService
  -> authenticated WSS session -> companion -> authorized Obsidian APIs

The gateway package does not provide a production executable, account system, database implementation, or remote MCP HTTP authentication layer. An operator must supply those boundaries, TLS, independent HMAC secrets from a secret manager, operational retention rules, and account/device management. Never use the in-memory auth or repository classes in production.

See Remote bridge deployment for required composition, suggested operator configuration, credential expiry/re-pair behavior, and troubleshooting.

Checks and Builds

Targeted TypeScript commands:

pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm verify:release

pnpm verify runs the complete recursive sequence. pnpm verify:release is the fast metadata-only release check: it validates versions, manifests, configs, documentation/tool coverage, asset placeholder state, deployable declarations, and obvious credentials in non-test source/config files.

Preserved Python checks and build:

uv run ruff check .
uv run pytest
uv build

Security Model

• Vault content is untrusted data, including quoted, linked, and embedded notes.
• Filesystem paths are normalized and constrained to configured roots; absolute paths, traversal, .obsidian/, excluded roots, and symlink escape are rejected.
• Scopes are operation-specific. Local single-vault configuration defaults to read-only.
• Existing-note writes require the expected SHA-256 revision. All writes require an idempotency key and default to dry-run.
• Full-document replacement, move, and trash require a reviewed plan and single-use confirmation. Trash moves notes to a Workbench trash location rather than hard deleting.
• Remote routing binds account, device, vault, and scope; offline writes are not queued.
• Tool errors and audit records avoid note bodies, credentials, and internal exception detail.

These controls reduce risk but do not make an untrusted MCP host, compromised local account, malicious Obsidian plugin, or compromised remote operator safe. Read the complete Threat model, Privacy placeholder, and Terms placeholder.

Current Limitations

• Production remote deployment is incomplete: no durable GatewayRepository, production AuthProvider, service bootstrap, account UI/API, account deletion workflow, key rotation procedure, or remote MCP authentication endpoint is included.
• Companion events are schema-validated and vault-bound through GatewayEventSink, but no production sink or MCP App cache-invalidation subscription is composed. Remote event delivery remains an operator integration step.
• Local idempotency and confirmation state is in memory and resets when the MCP server restarts.
• Local Streamable HTTP has no user authentication and is suitable only on loopback.
• Search is bounded lexical/metadata search; there is no semantic index or cloud index.
• Orphan/hub analysis inspects at most the first 200 notes and reports truncation.
• The MCP App is intentionally focused. It does not replace Obsidian, auto-save, or expose every registered tool.
• Public privacy terms, service terms, operator identity/contact details, retention periods, account-deletion SLA, data residency/subprocessors, and production assets require owner/legal approval. Current documents are explicit placeholders, not legal promises.
• No repository license file is present. Public distribution terms require owner approval.

Documentation

• Architecture
• Threat model
• Tool catalog
• Privacy placeholder
• Terms placeholder
• Local development
• Remote bridge
• Release checklist
• Production asset specifications

Preserved Python/FastMCP Prototype

This repository still contains the original dailynotesmcp Python 3.12/FastMCP greeting prototype. It exposes the hello_mcp_world prompt and read-only say_hello_mcp_world tool. It does not expose Obsidian Workbench vault tools or vault data.

The existing .mcp.json, .codex-mcp.json, .claude-plugin/, .codex-plugin/, .agents/plugins/, api/index.py, and vercel.json remain the legacy marketplace/deployment configuration for https://dailynotesmcp.vercel.app/mcp. They are intentionally distinct from the Workbench examples under config/.

Run it locally with:

uv run dailynotesmcp
# HTTP MCP: http://localhost:8000/mcp
# Health:   http://localhost:8000/health

Or use the packaged STDIO entry point:

uv run dailynotesmcp-stdio

Vercel continues to deploy only this stateless Python prototype through api/index.py. vercel.json disables framework and root build-command detection, and constrains static output to the minimal public/ directory, so the TypeScript workspace does not become a frontend deployment or static source tree. Do not describe that public endpoint as an Obsidian Workbench remote bridge.

Release

The TypeScript suite and Python prototype currently share one repository version/tag. Before tagging vX.Y.Z, update the root/workspace package versions, Obsidian companion manifest, Python project version, and preserved legacy plugin versions together. Then run both language check sets and complete the public release checklist.

The release workflow verifies both stacks, builds Python distributions and TypeScript artifacts, packages the Obsidian deployables and single-file MCP App, and creates a draft GitHub release. An owner must resolve all legal, privacy, security, asset, and operational placeholders before publishing it.