ObsidianMCP

A lightweight, secure Model Context Protocol (MCP) server for seamless Obsidian vault integration with AI assistants and automation tools.

Interact with your Obsidian vault through MCP-compatible clients like Claude Desktop, VSCode, or any other MCP-enabled application.

Features

• List notes - Browse your entire vault structure with folder hierarchy
• Read notes - Access note content securely
• Create notes - Add new notes with initial content
• Append content - Extend existing notes
• Delete notes - Remove notes safely
• Search - Find notes by name or content
• Health checks - Monitor server status and vault accessibility

Perfect for integrating Obsidian with AI agents, building automations, and creating advanced workflows.

Available Tools

| Tool | Description | Parameters | | ---------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------- | | check_health | Check server health and vault accessibility. | — | | list_notes | List all markdown notes with folder hierarchy. | — | | read_note | Read the content of a specific note. | note: Note path (e.g., Personal/Diary.md) | | create_note | Create a new note. Fails if it already exists. | note: Note pathcontent: Initial content (optional) | | append_to_note | Append content to an existing note. | note: Note pathcontent: Text to append | | delete_note | Delete a note. This action is irreversible. | note: Note path | | search_notes | Search notes by name or content. | query: Search textsearchContent: Also search content (optional, default: false) |

Quick Start

Just add this to your MCP client configuration:

Claude Code

Edit ~/.claude.json:

{
  "mcpServers": {
    "obsidian": {
      "type": "stdio",
      "command": "npx",
      "args": ["@manex/obsidianmcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "~/Documents/ObsidianVault"
      }
    }
  }
}

VSCode (Copilot)

Edit ~/.config/Code/User/mcp.json:

{
  "servers": {
    "obsidian": {
      "type": "stdio",
      "command": "npx",
      "args": ["@manex/obsidianmcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "~/Documents/ObsidianVault",
      },
    },
  },
}

Replace ~/Documents/ObsidianVault with your actual Obsidian vault path. You can use ~ for the home directory.

Note: OBSIDIAN_VAULT_PATH must point to an existing Obsidian vault directory.

Development

Requirements

• Node.js v18+ (or Bun v1.0+ for development build)
• Obsidian vault (local directory)

Available Scripts

| Command | Description | | ------------------- | ------------------------------- | | bun run dev | Run server in development mode | | bun run build | Build for production | | bun run start | Run the compiled server | | bun test | Run test suite | | bun test --watch | Run tests in watch mode | | bun run typecheck | Type check with TypeScript | | bun run inspector | Run MCP inspector for debugging |

Project Structure

src/
├── server.ts          # MCP server entry point
├── config/            # Configuration & environment validation
├── errors/            # Typed error classes
├── schemas/           # Zod input validation schemas
├── tools/             # MCP tool implementations
├── types/             # TypeScript type definitions
└── utils/             # File system & security utilities

Security

Built with security as a first-class concern:

• Path traversal prevention - Validates all paths against vault boundaries
• Symlink escape detection - Prevents breaking out via symbolic links
• DoS protection - Limits recursion depth and result counts
• TOCTOU prevention - Atomic file operations for safe concurrent access
• Input validation - All inputs validated with Zod schemas

License

MIT

Support

Found a bug or have a feature request? Open an issue.

Built with Bun and Model Context Protocol SDK