glasswing-mcp

A standalone MCP server for Obsidian vaults, purpose-built for agentic coding workflows with Claude Code and OpenCode. Operates directly on the vault filesystem — no Obsidian app, no plugins, no REST API bridges, no network calls.

The MCP server that gives your Obsidian vault wings.

Glasswing: obsidian is volcanic glass — this server gives your agent wings over it.

Why This Exists

Agentic coding clients work best when a knowledge source is local, stable, and cheap to keep in context. Obsidian vaults are already plain folders of markdown, so glasswing-mcp treats the vault filesystem as the source of truth instead of requiring the Obsidian app, a plugin, a REST bridge, or any network service.

The design goals are simple:

• Standalone operation — run with Node.js and a vault path; no Obsidian app process, community plugin, REST API, SSE server, or network endpoint.
• Claude Code / OpenCode friendly transport — stdio only, with all diagnostics on stderr so JSON-RPC stays clean.
• Small tool surface — six focused tools with a measured schema budget below 3,000 tokens, plus paginated and clipped outputs so retrieval does not flood the context window.
• Obsidian-native navigation — tag search, frontmatter queries, backlink traversal, aliases, section reads, pagination, attachments, and multi-vault routing over ordinary markdown files.

glasswing-mcp is optimized for the common agent flow: search narrowly, read the exact note or section on demand, and keep private vault content local.

Quick Start (zero config)

Install the server:

npm install -g glasswing-mcp

Add the MCP server to ~/.claude.json or a project .mcp.json:

{
  "mcpServers": {
    "vault": {
      "command": "glasswing",
      "args": ["/path/to/your/vault"]
    }
  }
}

Verify the server starts through the MCP Inspector:

npx @modelcontextprotocol/inspector glasswing /path/to/your/vault

Multiple vaults

glasswing /path/to/work-vault /path/to/personal-vault --name work --name personal

The first vault is the default — tools behave exactly as single-vault mode unless a vault parameter is passed. Cross-vault search is opt-in via --cross-vault-search.

Tools

| Tool | Purpose | Typical cost | |------|---------|-------------| | obs_search | Full-text, tag, or frontmatter search (single query param, mode-dependent) with cursor pagination | ~1,000–3,000 tokens | | obs_read | Read full file, section (with duplicate-heading disambiguation), frontmatter, or line range | ~100–4,000 tokens | | obs_write | Create, append, surgical patch (str_replace style), set frontmatter (merge/update; null deletes), delete, or move (with to) | ~50 tokens response | | obs_links | Backlinks, outlinks (wikilink + markdown), orphan detection | ~200–800 tokens | | obs_list | Folder listing with depth control, attachments, frontmatter summaries | ~500–2,000 tokens | | obs_tags | Tag index with hierarchical grouping and counts | ~300–1,500 tokens |

Total schema overhead: ≤3,000 tokens (1037 measured 2026-06-17 for the six obs_* tools, including optional vault parameters).

Design Principles

1. The server is mechanical, the LLM is intelligent. The server indexes, retrieves at requested granularity, and formats for readability. It never decides what's relevant — the LLM owns relevance judgment.
2. Return pointers by default, content on demand. Search returns titles, snippets, and paths. Full content requires an explicit obs_read.
3. Structured plain text, not XML/JSON. Output is markdown with consistent structural headers — the format LLMs reason over best.
4. stdio transport only. No idle timeouts, no auth handshake, no DNS rebinding, no firewall questions. OS manages process lifecycle.
5. Vault is just a folder of .md files. No Obsidian app, no plugins, no REST API. If the files exist on disk, the server works.
6. Zero network calls, ever. Your vault never leaves your machine. Safe for journals, therapy notes, and anything else private.

Make Your Vault Agent-Friendly (optional)

If an AGENTS.md file exists at the vault root, glasswing forwards a trimmed version through the MCP instructions handshake — the agent learns your vault's layout and conventions before its first tool call. Example:

# AGENTS.md
Specs live in /projects. Daily notes in /journal — skip unless asked.
`status: active` means in-flight. MOC-*.md files are navigation entry points.

No AGENTS.md? Everything still works — the agent explores via obs_list and obs_tags instead.

Tuning (optional)

Configuration precedence: CLI flags / env vars → vault-root .glasswing.json → built-in defaults.

// .glasswing.json (at vault root — travels with the vault)
{
  // Safe glob/prefix ignore language. No regex syntax.
  "ignore": ["Archive", "Templates/**", "**/*.tmp"]
}

The vault file is for loader tuning only. Search result limits and write safety come from tool parameters, CLI flags, environment variables, and built-in defaults.

Security exception: read_only is honored only from CLI (--read-only=false) or env (GLASSWING_READ_ONLY=false) — never from the vault-resident file. A synced or cloned vault must not be able to grant itself write access.

Safety Notes

• Writes are off by default. Enable explicitly via CLI/env. Writes are restricted to .md files inside the vault; frontmatter writes are gated by a round-trip fidelity check.
• Prompt injection: note content flows into your agent's context as tool output. A note in a shared or cloned vault containing adversarial instructions is a real vector that no server can fully neutralize. Be deliberate about pointing agents at vaults you didn't write.
• Path containment: all paths are resolved and verified to stay inside the vault; symlinks that escape the vault are rejected.

Performance (measured)

Measured index build / load time and RSS (Windows, Node v22.18.0, 2026-06-17). Single-run local snapshot. CI validates the harness contract only; the 1k/5k/20k rows are not re-measured in CI. See docs/benchmarks.md for the PRD distinction.

| Vault size | Index load | RSS | RSS target | Verdict | |------------|------------|--------|------------|---------| | 1,000 | 173 ms | 86 MB | — | — | | 5,000 | 1.27 s | 110 MB | — | — | | 20,000 | 1.94 s | 138 MB | < 200 MB | ✅ met |

See docs/benchmarks.md for methodology and reproduction.

Files up to 10k lines are first-class: section reads are substring operations on cached line offsets, and note bodies are not held in memory at rest.

Requirements

• Node.js 20+
• An Obsidian vault (or any folder of markdown files with optional YAML frontmatter)
• An MCP client that supports stdio transport (Claude Code, OpenCode, Claude Desktop)

Windows, macOS, and Linux are all first-class (CI-tested on all three).

License

MIT