Self-hosted Obsidian-compatible markdown vault with a web UI and a 57-tool MCP server for AI agents
The io.github.daniele-chiappa/gosidian MCP server provides a self-hosted, Obsidian-compatible markdown vault with a web UI. It exposes a 57-tool MCP server for AI agents to interact with the vault’s content.
🛠️ Key Features
Self-hosted Obsidian-compatible markdown vault
Web UI
MCP server with 57 tools
🚀 Use Cases
Enable AI agents to work with an Obsidian-style markdown vault
Provide web access to the vault alongside MCP tool access
⚡ Developer Benefits
Fixed tool set available via MCP (57 tools)
Compatible with an Obsidian-compatible vault workflow
⚠️ Limitations
Scope described only as an Obsidian-compatible vault plus web UI and a 57-tool MCP server; no further capabilities are provided in the source data.
Markdown notes your AI agents can read, write, and reason over — via MCP.
A self-contained markdown vault with a built-in MCP server. Humans
edit through a web UI, agents talk to it over MCP, everything lives
in plain .md files that Obsidian (and every other markdown tool)
reads natively.
Launch a free, throwaway gosidian in
GitHub Codespaces — no install,
running on your own Codespaces quota. It builds from source, seeds a small
demo vault, and opens the web UI. Log in with demo /
gosidian-demo.
Quick start
bash
docker run -d --name gosidian \
-p 8080:8080 \
-v "$(pwd)/vault:/vault" \
ghcr.io/daniele-chiappa/gosidian:latest
# open http://localhost:8080, create admin, copy the MCP token from /admin/tokens
claude mcp add gosidian http://localhost:8080/mcp \
--transport http --header "Authorization: Bearer $TOKEN"
Three commands: Docker up → token created from the web UI → agent
wired. Your .md vault is persisted under ./vault/; stop the
container and the files are still there.
A markdown vault. Notes are .md files on disk. Open the same
folder in Obsidian, VS Code, vim, or any editor you already use.
Zero lock-in: delete .gosidian/ and you have a pure Obsidian
vault.
An MCP server. 57 typed tools let agents bootstrap a session, ingest files,
search, read, write, link, handoff, self-check, audit. Bearer tokens
and OAuth grants, each narrowed on every request to what its account
may read and write.
A web UI. A Vue 3 single-page app served from the same binary
(built with Vite, embedded via go:embed). Notes, graph, search and
config forms open as windows in a tiling "plancia" workspace —
full-text search, backlinks, graph view, editor with live preview,
audit trail, admin pages for tokens and users.
All three views hit the same files on disk. The SQLite FTS5 index
is a cache — drop it and it rebuilds.
Who it's for
AI engineers wiring agents that need persistent structured
memory: note-taking, plans, skills, ADRs, handoffs, audit.
Obsidian users who want a programmable layer on top of a vault
they already trust.
Teams sharing one vault: per-project visibility and grants to
accounts and teams, restricted new accounts with their own project,
self-service tokens per agent that never outrun their owner.
Why gosidian instead of X
vs RAG / vector search: gosidian retrieves by identity (path,
tag, frontmatter, backlinks) — more predictable than similarity
search for an agent's working memory. Semantic search is
deliberately deferred: see ADR-007 rationale.
vs Obsidian Sync: Sync mirrors a vault between human devices.
gosidian adds a typed automation surface (MCP) to the same vault.
Not competitive — complementary.
vs Notion / Roam: hosted or proprietary formats; migration is
a project. gosidian's vault is already .md files you can take
anywhere.
Expose a running Obsidian desktop app to agents over MCP.
Headless server: no Obsidian process needed, runs on a box or in a container, multi-user with roles, per-project visibility and grants (accounts and teams), tokens narrowed to each account, audit trail. The vault stays a plain Obsidian vault.
Same "files, not a database" idea; usually add hybrid semantic search, a cloud tier or WebDAV sync.
Ships a full web UI, real multi-user, an agent handoff bus and a server-served working method (versioned directives, lint, stale detection). No semantic search by design (ADR-007), no hosted tier.
Client-side wiki skills — obsidian-wiki and the "LLM Wiki" pattern
Slash-commands the agent runs locally to compile and maintain a wiki. No server, no auth, no UI.
The same pattern implemented server-side and agent-agnostic: one-call scaffold, directives served at bootstrap, handoffs, audit. Complementary: those skills work against a gosidian vault too.
Memory as an opaque store: embeddings, recall benchmarks, auto-capture hooks.
Memory is markdown that humans read in Obsidian or the web UI; no embeddings, no LLM calls in the binary, retrieval by identity and graph. Auto-capture through Claude Code hooks (contrib/claude-code/: focus injected at session start, session digests at compaction and end) rather than inside the binary. No published recall numbers yet.
Mature editors, mobile apps, sometimes real-time collaboration; MCP added by third-party servers on top of their API.
MCP-first: the server is in the binary, behind the same login, roles and audit as the UI. No mobile app, no real-time collaboration, no WYSIWYG editor.
Honest gaps, in the order they come up: semantic / hybrid search
(deferred, see the FAQ),
mobile sync beyond git, real-time collaboration, a hosted offering. The
roadmap says which of these are planned.
Feature highlights
Single binary, ≤50 MB, Alpine-based Docker image
Web UI: a Vue 3 SPA (Vite, Pinia, Tailwind, CodeMirror, Cytoscape),
embedded in the binary — editor + live preview, sidebar, search,
graph view, attachments, audit log, admin pages
Plancia tiling window manager (niri-style): notes, graph, search
and config forms open as resizable, side-by-side windows in a
horizontally-scrollable workspace, restorable from the URL
MCP server over Streamable HTTP (legacy HTTP+SSE kept) with 57 typed tools
Bearer tokens with scopes (read / write) and per-project
restriction — including multi-project tokens for orchestrators;
every token owned by an account is narrowed on each request to what
that account may read and write, accounts mint their own (inherit
follows their access, custom pins a subset), cascade-revoke on
user disable
Agent orchestration bus: handoff notes with an atomic
claim/complete lifecycle, server-stamped identity, and a
memory_wait_changes long-poll change feed — a minimal multi-agent
task queue where everything stays plain markdown
Multi-user web login with roles (Admin / User / Read-only) as the
ceiling, per-project visibility (private / internal / public) for
reading and grants (read / write / admin) to accounts and
teams for everything else, delegated to project admins; new
accounts start restricted with a personal project of their own;
invite-only signup (24h TTL)
Optional TOTP two-factor (global mode + per-user override) and
LDAP / Active Directory login with guest auto-provisioning
Opt-in OAuth 2.1 authorization server so claude.ai / Claude Desktop
custom connectors, ChatGPT connectors and Claude Code's browser login
get their own tokens through a consent screen — no pasted bearer
Claude Code hooks (contrib/claude-code/):
the project's hot.md focus injected at every session start, a
digest of the session appended to the vault at compaction and at the
end — no LLM, over POST /mcp/append, never blocking the session
Optional git sync (debounced commits, push with token auth)
