MCP server (AI agents)

Vault CMS ships with a Model Context Protocol server bundled inside the same create-vaultcms npm package. Once registered, AI tools like Claude Code, Cursor, Claude Desktop, and Codex can install and configure Vault CMS for you through structured tool calls, no need to switch to a terminal or answer interactive prompts.

Why this matters

Without MCP, asking an AI for help with Vault CMS gets you a tutorial. The AI tells you to cd to your project, run npx create-vaultcms, pick options, and so on. You do the work.

With MCP registered, the same conversation goes:

“Set up Vault CMS in my Astro project at ~/code/my-blog using the Starlight preset.”

The agent inspects the project, confirms it’s Astro, picks the right install location, runs the install, and reports what changed, all in one turn.

Quick start

The server speaks stdio. AI clients spawn it as a subprocess. You only need to register it once per tool.

Claude Code

Run the registration command (one line):

claude mcp add vaultcms --scope user -- npx -y -p create-vaultcms@latest vaultcms-mcp

That writes the server entry to your user-level Claude config. Restart Claude Code and the three tools become available.

To allow the tools without permission prompts, open ~/.claude/settings.json and add "mcp__vaultcms__*" to the permissions.allow array.

Cursor

Open Settings → Cursor Settings → MCP → Add new MCP server:

• Name: vaultcms
• Type: command
• Command: npx -y -p create-vaultcms@latest vaultcms-mcp

Claude Desktop

Edit claude_desktop_config.json (location varies by OS, see the Claude Desktop docs):

{
  "mcpServers": {
    "vaultcms": {
      "command": "npx",
      "args": ["-y", "-p", "create-vaultcms@latest", "vaultcms-mcp"]
    }
  }
}

Restart Claude Desktop. The vaultcms tools appear in the tool picker.

Other MCP-compatible clients

Anything that runs an MCP stdio server can use it. The launch command is always:

npx -y -p create-vaultcms@latest vaultcms-mcp

What the agent can do

The server exposes three tools.

detect_project (read-only)

Inspects a directory and returns a structured snapshot:

• Whether it’s an Astro project
• The resolved project root (walks up looking for package.json, astro.config.*, or .git)
• Detected package manager (pnpm, yarn, bun, npm)
• Content collections under src/content/ (filtered to exclude Vault CMS install artifacts)
• Dynamic Astro routes ([...slug].astro) mapped to their content collections
• Whether Vault CMS is already installed
• Whether any Obsidian vault is present (even without the vault-cms plugin, protects older Obsidian-authored sites from being overwritten)

The agent uses this to confirm the project state before doing anything.

list_presets (read-only)

Returns the available preset templates from the registry, with metadata pulled from the vaultcms-presets manifest:

• Name (e.g. starlight)
• Display name and description
• Default install target (typically src/content)
• Theme association

Defaults to the official davidvkimball/vaultcms-presets registry. See Custom preset registries below for using a fork.

install_vaultcms (mutating)

Runs the full install programmatically, equivalent to npx create-vaultcms minus the interactive prompts:

• Downloads the vault config (and optionally a preset zip)
• Copies _bases/ and .obsidian/ into the target directory
• Fixes paths in .obsidian/plugins/vault-cms/data.json so they’re vault-relative
• Adjusts Home.base formulas, app.json, and Explorer Focus config based on whether you installed at project root vs. src/content
• Updates .gitignore with the standard Vault CMS entries

Returns a structured result with modifiedPaths, gitignore action, and the captured installer log.

The tool refuses by default if it detects an existing Obsidian vault without the vault-cms plugin, prevents an agent from silently clobbering an older Obsidian-authored setup. Pass force: true to override after the user explicitly confirms.

What the server intentionally doesn’t do

• No GUI launches. The interactive CLI offers to open Obsidian after install; the MCP server returns a hint string instead. Reason: agents shouldn’t trigger windows the user didn’t ask for.
• No automatic Git commits. The Git plugin runs locally inside Obsidian; the MCP doesn’t drive it.
• No interactive prompts. Everything is structured args in, structured data out. The agent does the asking.

Custom preset registries

Both list_presets and install_vaultcms default to davidvkimball/vaultcms-presets, but you can point them at a fork or a private team registry. Three converging override paths (priority order):

1. Per-call argument: agent can pass source to list_presets or presets_repo to install_vaultcms
2. CLI flag: npx create-vaultcms --presets-repo owner/repo
3. Environment variable: VAULTCMS_PRESETS_REPO=owner/repo

Format is owner/repo or owner/repo@branch. Branch defaults to master. Examples:

# CLI
npx create-vaultcms --presets-repo acme/vaultcms-presets

# Env var (zero-config, once set, all flows pick it up)
export VAULTCMS_PRESETS_REPO=acme/vaultcms-presets
npx create-vaultcms

// MCP arg
{
  "tool": "install_vaultcms",
  "arguments": {
    "target_path": "src/content",
    "template": "myth",
    "presets_repo": "acme/vaultcms-presets@dev"
  }
}

Caution

A custom registry runs code on your machine, install_vaultcms downloads a zip and extracts it into your project. Only use registries you trust.

A typical agent flow

What a good prompt → agent → install loop looks like:

1. You: “Set up Vault CMS in my Astro project at ~/sites/blog using Slate.”
2. Agent calls detect_project({ path: "~/sites/blog" }) → confirms Astro, pnpm, no Vault CMS yet, no pre-existing Obsidian setup
3. Agent calls list_presets() → confirms slate exists, sees it installs at src/content
4. Agent confirms with you: “This is an Astro project using pnpm. I’ll install Vault CMS with the Slate preset at ~/sites/blog/src/content. Proceed?”
5. You: “Yes.”
6. Agent calls install_vaultcms({ target_path: "~/sites/blog/src/content", template: "slate" }) → returns success with modified paths
7. Agent tells you: “Done. Open Obsidian → ‘Open folder as vault’ → select ~/sites/blog/src/content. Then run Vault CMS: Open Wizard to finish setup.”

You typed two short messages. The agent handled the rest.

Safety guards

• install_vaultcms is mutating: confirm with the user before invoking. The tool description marks it as such, so well-behaved agents will ask first.
• Existing Obsidian vault protection: install refuses by default if any .obsidian/ directory exists in the project root, src/content/, or any first-level content collection without the vault-cms plugin. This catches older Obsidian-authored sites that predate the plugin and prevents silent overwrites of workspace, hotkeys, themes, and plugin lists.
• Custom registries warn the user: both tool descriptions and the docs explicitly note that custom presets_repo values download and execute code from third-party repos.

Verifying it works

A quick sanity check from your shell:

# Should boot, log to stderr, and respond on stdin
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"manual","version":"0"}}}' \
  | npx -y -p create-vaultcms@latest vaultcms-mcp

You should see vaultcms-mcp <version> ready (stdio) on stderr and a JSON-RPC response on stdout.

Inside the AI tool itself, ask: “Use the vaultcms MCP to detect the project at the current directory.” You should get back a structured JSON snapshot.

Source and reporting issues

• npm package: create-vaultcms
• Source: github.com/davidvkimball/vaultcms, src/mcp.js and src/lib/
• Bundled spec: MCP.md inside the package
• Issues: GitHub Issues