obsidian-agi-workspace-mcp
This server exposes an Obsidian vault workspace with note/folder management, search/analysis, and X Article publication-request workflows.
Create and list folders; get a filtered vault tree.
Read, write, overwrite, patch, and delete (trash/permanent) Markdown notes with frontmatter support.
Search notes by keyword/tags/frontmatter/folder; list tasks by tag, folder, completion.
Analyze workspace wikilink graph: nodes, edges, orphans, dangling links.
Render X Article previews, create/deduplicate X publish requests, and read publication status.
The schema also includes sync_vault_ob for ob sync status/sync/configure, though the README states this tool is deliberately not exposed.
Provides tools for managing Obsidian vaults, including searching, reading, writing, and patching notes, managing folders and tasks, resolving wikilinks and backlinks, analyzing the workspace graph, and syncing with Obsidian Headless Sync.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@obsidian-agi-workspace-mcp aggregate all unchecked tasks in my vault and show them by project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
obsidian-agi-workspace-mcp
A security-boundary-first MCP workspace for an Obsidian vault, with controlled X Article publication requests.
v0.2 status: local development and manifest validation are supported. The checked-in Kubernetes manifests are intentionally not production-ready until the encrypted Talos volume, pinned release images, MCP token, Obsidian login, allowed hostname, and target node have been supplied and verified.
Architecture
Obsidian desktop vault
⇅ Obsidian Sync E2EE
Talos LUKS2 UserVolume / one PVC
├── vault/ mounted only by ob sync
│ └── projects/x-blog/ the only subtree mounted into MCP
│ └── .x-publish/ non-secret requests and receipts
└── ob-home/ mounted only by ob sync
Authenticated Streamable HTTP MCP
├── read/search/edit allowed notes
├── render_x_preview
├── request_x_publish no X network call
└── get_x_publication_status
Local obsidian-x-publisher
├── reads the synced request
├── verifies the current Markdown SHA-256
├── requires --yes + --expected-sha
└── invokes local xurl credentials to create/publish an ArticleTrust boundaries
The MCP container does not mount the complete vault, Obsidian credentials, or X credentials.
The
obsidecar mounts the complete vault and its own persistent home; MCP does not.X OAuth remains in the local
xurlhome. It is never placed in Git, the Obsidian vault, the MCP Pod, Kubernetes manifests, or publication receipts.obruns continuously in one sidecar. MCP clients cannot invoke or reconfigure it.Network MCP uses stateless Streamable HTTP at
/mcp, a Bearer token, an HTTP Host allowlist, a 1 MiB request limit, and no wildcard CORS.X writes are two-stage: the MCP creates an immutable request; the local publisher creates a draft and later publishes it.
A request ID is a deterministic idempotency hash over schema version, publication type, account, source path, and source SHA-256.
Encryption at rest does not protect plaintext from a compromised running Pod. The runtime boundaries above remain necessary even with LUKS2.
Related MCP server: Obsidian MCP Server
MCP tools
Tool | Side effect | Purpose |
| Vault write | Create a folder inside the configured boundary. |
| None | List permitted folders. |
| None | Return only permitted paths; sibling folders are filtered. |
| None | Read a Markdown note and metadata. |
| Vault write | Create or overwrite a note. |
| Vault write | Patch body, sections, regex matches, or frontmatter. |
| None | Search permitted notes. |
| None | Collect Markdown tasks. |
| None | Build the permitted wikilink graph. |
| Vault write | Trash an item by default; deleting the vault root is rejected. |
| None | Render the verified X Article payload and source hash. |
| Queue write | Create/deduplicate a non-secret publication request. |
| None | Read requested/draft-created/published status. |
There is deliberately no sync_vault_ob, arbitrary shell, X token inspection, or direct X publish MCP tool.
Local development
Requirements: Node.js 22+, pnpm 11, and go-task.
pnpm install --frozen-lockfile
task checkStdio mode:
OBSIDIAN_VAULT_PATH=/absolute/path/to/vault \
OBSIDIAN_ALLOWED_SUBPATHS=projects/x-blog \
pnpm devAuthenticated HTTP mode:
# Create the token file outside the repository and chmod it 0600.
OBSIDIAN_VAULT_PATH=/absolute/path/to/vault \
OBSIDIAN_ALLOWED_SUBPATHS=projects/x-blog \
X_PUBLISH_QUEUE_PATH=projects/x-blog/.x-publish \
MCP_TRANSPORT=streamable-http \
MCP_AUTH_TOKEN_FILE=/absolute/private/path/mcp-token \
MCP_ALLOWED_HOSTS=127.0.0.1,localhost \
HOST=127.0.0.1 PORT=8080 \
pnpm devHealth endpoints are /healthz and /readyz; the MCP endpoint is /mcp.
Hermes HTTP client shape:
mcp_servers:
obsidian-workspace:
url: "https://mcp.example.invalid/mcp"
headers:
Authorization: "Bearer <load-this-from-your-secret-management-workflow>"
sampling:
enabled: falseDo not commit a real token in Hermes configuration examples or this repository.
X Article workflow
One-time local setup
Install and authenticate the official xurl CLI manually, outside an agent session. Never paste X credentials into chat or add inline secrets to commands. The safe agent-visible check is:
xurl auth statusThe account with X credentials is the only Publisher.
Request from MCP
Call
render_x_previewwithsourcePath.Review title, body length, payload, and
sourceSha256.Call
request_x_publishwith the same path and target X handle.Wait for Obsidian Sync to report
Fully syncedon the local publisher copy.
Create and publish locally
Use the request ID and exact source hash returned by MCP:
export OBSIDIAN_VAULT_PATH=/absolute/path/to/local/vault
export OBSIDIAN_ALLOWED_SUBPATHS=projects/x-blog
export X_PUBLISH_QUEUE_PATH=projects/x-blog/.x-publish
obsidian-x-publisher status <request-id>
obsidian-x-publisher draft <request-id> \
--expected-sha <source-sha256> --app <xurl-app-name> --yes
obsidian-x-publisher publish <request-id> \
--expected-sha <source-sha256> --app <xurl-app-name> --yesThe publisher refuses a stale or mismatched source hash. Receipts contain only request/hash/status/timestamp and public Article/Post IDs.
Current scope is X Articles. The public API does not provide unrestricted editing of published Articles. Ordinary Post editing has separate X account, plan, and time-window constraints and is not represented as an always-available tool.
Talos encrypted storage gate
The example deploy/talos/obsidian-workspace-volume.example.yaml targets Talos 1.13+ and defines a LUKS2 UserVolumeConfig using TPM with lockToState. It intentionally contains a nonfunctional WWID placeholder.
Before any apply:
Inspect the real node with
talosctl get disks -o yamlandtalosctl get discoveredvolumes -o yaml.Prove the selected WWID is the intended non-system data disk.
Confirm TPM 2.0 and SecureBoot. If unavailable, design and review a KMS key path instead; do not downgrade to a committed static passphrase.
Copy the example into the infra repository and replace the WWID there.
Preview the exact live-node patch:
talosctl patch machineconfig \ --talosconfig <repo-local-talosconfig> \ --nodes <verified-node> \ --patch @<reviewed-volume-patch.yaml> \ --dry-runApply only in an approved storage maintenance workflow with a rollback/recovery plan.
Verify
volumestatus u-obsidian-workspace,mountstatus u-obsidian-workspace, and the LUKS2 mapper/filesystem chain indiscoveredvolumes.
The Kubernetes PV example maps /var/mnt/obsidian-workspace, pre-binds the exact claim, uses node affinity, and retains data. Replace REPLACE_WITH_VERIFIED_NODE_NAME before use.
Kubernetes deployment gate
deploy/k8s/deployment.yaml expects:
published
0.2.0MCP and ob-sync images, pinned by digest in the production overlay;StorageClass/PV
obsidian-workspace-encryptedbacked by the verified Talos LUKS2 volume;Secret
workspace-mcp-authwith keytoken;Hermes clients in the
devboxnamespace;the selected node label and
edge-ustoleration;the manual bootstrap in
deploy/k8s/bootstrap.example.yamlto complete before either long-running service starts.
The ob-sync and MCP containers run in separate Pods. The sync Pod can reach DNS and HTTPS; the MCP Pod accepts port 8080 only from devbox and has no egress. The only MCP-mounted content is vault/projects/x-blog.
Create the MCP Secret from a private file rather than an inline shell value:
kubectl -n obsidian-workspace create secret generic workspace-mcp-auth \
--from-file=token=/absolute/private/path/mcp-token \
--dry-run=client -o yaml > /private/path/workspace-mcp-auth.generated.yaml
kubectl apply -f /private/path/workspace-mcp-auth.generated.yamlKeep the generated Secret manifest outside Git and delete it securely after application.
Bootstrap Obsidian only after the encrypted PVC is Bound. Do not add the bootstrap Pod to Flux:
kubectl apply -f deploy/k8s/bootstrap.example.yaml
kubectl exec -it -n obsidian-workspace pod/obsidian-workspace-bootstrap -- ob login
kubectl exec -it -n obsidian-workspace pod/obsidian-workspace-bootstrap -- ob sync-list-remote
kubectl exec -it -n obsidian-workspace pod/obsidian-workspace-bootstrap -- \
ob sync-setup --vault oh-my-obsidian --path /vault --device-name prod-us-workspace-mcp
kubectl exec -it -n obsidian-workspace pod/obsidian-workspace-bootstrap -- \
ob sync-config --path /vault --mode pull-only --conflict-strategy conflict
kubectl exec -it -n obsidian-workspace pod/obsidian-workspace-bootstrap -- ob sync --path /vaultWait for Fully synced; a running Pod is not enough. Stop the old cluster-side continuous sync writer, run one final pull, switch the new client to bidirectional mode, and only then create the sentinel:
kubectl exec -it -n obsidian-workspace pod/obsidian-workspace-bootstrap -- \
ob sync-config --path /vault --mode bidirectional --conflict-strategy conflict
kubectl exec -it -n obsidian-workspace pod/obsidian-workspace-bootstrap -- ob sync --path /vault
kubectl exec -n obsidian-workspace pod/obsidian-workspace-bootstrap -- \
sh -c 'touch /home/obsidian/.bootstrap-complete'
kubectl delete -n obsidian-workspace pod/obsidian-workspace-bootstrapBoth Deployments wait for that sentinel, preventing an empty or partially initialized vault from being exposed through MCP.
Security notes
Symbolic-link traversal is rejected for every resolved path.
Allowed-subpath ancestors may be traversed only for filtered tree display; ordinary reads and writes must be inside an allowed subtree.
Publication requests use atomic no-clobber creation and receipts use atomic replacement.
HTTP token comparison uses constant-sized SHA-256 digests with timing-safe comparison.
The Kubernetes service is ClusterIP-only and guarded by a default-deny NetworkPolicy.
All containers run non-root, drop Linux capabilities, disallow privilege escalation, use a read-only root filesystem, and do not receive a service-account token.
src/crypto.tsremains a field/envelope utility; it is not presented as full-vault encryption. Talos LUKS2 protects persistent storage and Obsidian Sync E2EE protects the remote copy.
Verification
task check
task manifests:validate
task images:buildProduction acceptance additionally requires a real authenticated MCP client call, an Obsidian bidirectional sync probe, LUKS2 readback, and an X draft call before any public Article publish.
License
MIT © 2026 yunzaixi-dev
Available Tools
11 toolsanalyze_workspace_graphA
Analyze knowledge graph topology: nodes, wikilink edges, orphan notes, and dangling (broken) links.
Inputs: no named parameters.
create_folderB
Create a new folder or directory hierarchy inside the Obsidian vault.
Inputs: path (required).
delete_itemA
Safely delete a note or folder (moves to .trash by default).
Inputs: path (required), permanent.
get_vault_treeA
Retrieve hierarchical directory tree of folders and notes in the vault for workspace overview.
Inputs: maxDepth, subfolder.
list_foldersB
List folders and directory structure in the vault with note counts.
Inputs: parentFolder.
list_tasksA
Aggregate markdown task checkboxes (- [ ] / - [x]) across the Obsidian vault.
Inputs: tag, folder, completed.
patch_noteA
Perform fine-grained updates on an existing Obsidian note (append, prepend, replace under heading, regex patch, update frontmatter).
Inputs: path (required), append, prepend, patchRegex, +2 more.
read_noteA
Read an Obsidian note with frontmatter, body, metadata, wikilinks, and backlinks.
Inputs: pathOrTitle (required).
search_vaultA
Search vault notes by keyword, tags, frontmatter filters, or directory subpath.
Inputs: tags, limit, query, folder, +2 more.
sync_vault_obB
Trigger an immediate Obsidian Sync cycle or inspect synchronization state via obsidian-headless (ob).
Inputs: action (required), mode, conflictStrategy.
write_noteA
Create or overwrite a note in the Obsidian vault with structured YAML frontmatter and body.
Inputs: body (required), path (required), overwrite, frontmatter.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have clear boundaries: note operations (read/write/patch), folder operations (create/list/delete), and analysis (search/tasks/graph/sync) are distinct. Minor overlap exists between list_folders and get_vault_tree, but their descriptions (note counts vs. hierarchical tree) differentiate them enough.
The dominant pattern is verb_noun (create_folder, read_note, patch_note, search_vault). Exceptions are delete_item, which is generically named instead of delete_note_or_folder, and sync_vault_ob, where the '_ob' suffix is opaque and inconsistent with the rest of the API.
11 tools is well-scoped for an Obsidian workspace server. Each tool addresses a concrete operational need without excessive redundancy, and the count feels appropriate for the feature set.
The surface covers core workspace operations well: folder creation, note CRUD, search, task aggregation, graph analysis, sync, and deletion. Obvious gaps are rename/move operations for notes or folders, which would make the lifecycle more complete, but agents can generally work around this.
Maintenance
Related MCP Connectors
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Turn your notes, links and conversations into a Living Brain your AI tools share and build on.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI agents to explore, search, and manage local Obsidian vault documents with tools for document search, automatic frontmatter property generation, and attachment organization.543 npm2ISC
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to read, write, search, and navigate Obsidian vault notes with support for CRUD operations, full-text search, graph navigation, daily notes, and frontmatter management.4,114 npm-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to manage Obsidian vaults through full CRUD operations, wikilink management, and section-level manipulation. It supports frontmatter editing, tag-based searching, and automated link updates to maintain vault integrity.MIT
- -licenseNot gradedqualityNot gradedmaintenanceProvides AI agents with comprehensive access to Obsidian vaults, enabling reading, writing, searching, tagging, linking, canvas manipulation, and semantic search through 41 tools.-