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 path content: Initial content (optional)
append_to_note	Append content to an existing note.	note: Note path content: 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 text searchContent: 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