Another bloated Obsidian MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with secure access to Obsidian vaults. Enables reading, writing, searching, and managing notes without requiring Obsidian to be running.

Features

• Direct filesystem access - Works without Obsidian running

• Multi-vault support - Manage multiple vaults simultaneously

• Configurable tool groups - Enable only the features you need

• Full CRUD operations - Create, read, update, delete notes

• YAML frontmatter - Parse and manipulate note metadata

• Tag management - Add, remove, and search by tags

• Link analysis - Backlinks, outlinks, orphans, broken links, link graph

• Daily notes - Create and manage daily journal entries

• Templates - Apply templates with variable substitution

• Obsidian Bases - Query dynamic note views based on filters

• Batch operations - Process multiple notes efficiently

• Attachment tracking - List and find unused attachments

• Backup system - Create and restore note backups

• Security-first - Path traversal protection, symlink escape prevention

Requirements

• Node.js 18+

• npm or yarn

Installation

# Clone the repository
git clone https://github.com/yourusername/obsidian-mcp-server.git
cd obsidian-mcp-server

# Install dependencies
npm install
# or
yarn install

# Build (optional - can run directly with tsx)
npm run build

Quick Start

# Start the server with a vault
npm start /path/to/your/vault

# With specific tool groups
npm start /path/to/your/vault --tools=vault,notes,search

# With a custom vault name
npm start /path/to/your/vault my-vault

Configuration

Option 1: Claude Code CLI (Recommended)

# Add the MCP server
claude mcp add obsidian \
  --transport stdio \
  --scope user \
  -- npx tsx /path/to/obsidian-mcp-server/src/index.ts /path/to/vault

# With specific tool groups
claude mcp add obsidian \
  --transport stdio \
  --scope user \
  -- npx tsx /path/to/obsidian-mcp-server/src/index.ts /path/to/vault --tools=vault,notes,search

Scope options:

• user - Available in all projects (saved in ~/.claude.json)

• local - Current project only

• project - Shared with team (saved in .mcp.json)

Useful commands:

claude mcp list          # List configured servers
claude mcp get obsidian  # View server details
claude mcp remove obsidian  # Remove server

Option 2: Manual Configuration

Edit ~/.claude.json:

{
  "mcpServers": {
    "obsidian": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/obsidian-mcp-server/src/index.ts",
        "/path/to/your/vault",
        "--tools=vault,notes,search"
      ]
    }
  }
}

Option 3: Claude Desktop App

Edit the config file at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/obsidian-mcp-server/src/index.ts",
        "/path/to/your/vault",
        "--tools=vault,notes,search"
      ]
    }
  }
}

Tool Groups

Special values:

• all - Enable all tool groups (default)

• none - Disable all tools (for testing)

Configuration Examples

Read-Only Access

--tools=vault,notes,search

Safe for exploration without modifying notes.

Daily Productivity

--tools=vault,notes,search,daily,tags

Quick capture, daily notes, and tag organization.

Knowledge Analysis

--tools=vault,notes,search,links,tags

Explore connections, find orphans, analyze the knowledge graph.

Content Creation

--tools=vault,notes,search,templates,frontmatter

Create notes from templates, manage metadata.

Full Access

--tools=all

All features enabled.

Multi-Vault Setup

Create ~/.obsidian-mcp/config.json:

{
  "vaults": {
    "personal": "/Users/you/Obsidian/Personal",
    "work": "/Users/you/Obsidian/Work",
    "research": "/Users/you/Obsidian/Research"
  },
  "defaultVault": "personal"
}

Switch between vaults using set_active_vault tool.

Environment Variables

CLI Reference

# Show help
npm start -- --help

# Start with vault
npm start /path/to/vault [vault-name] [--tools=groups]

# Examples
npm start /path/to/vault                    # All tools
npm start /path/to/vault my-vault           # With custom name
npm start /path/to/vault --tools=vault,notes  # Specific groups

Troubleshooting

Server doesn't connect

1. Verify the vault path exists and is absolute

2. Check Node.js version: node --version (requires 18+)

3. Test manually: npm start /path/to/vault

4. For Claude Code: use /mcp to check status and errors

5. For Claude Desktop: check logs in ~/Library/Logs/Claude/mcp*.log

"Tool X is not enabled" error

The tool you're trying to use is not in your enabled groups. Check your --tools configuration and add the required group.

Permission errors

Ensure the user running the MCP server has read/write access to the vault directory.

Path not found

• Use absolute paths, not relative

• Ensure the vault contains a .obsidian folder

• Check for typos in the path

Development

# Development mode (auto-reload)
npm run dev

# Build
npm run build

# Type check
npx tsc --noEmit

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

Documentation

• API Reference - Complete tool documentation

• Architecture - System design

• Configuration - All configuration options

• Security - Security model

• Error Codes - Error reference

• Contributing - Development guide

Security

This server implements multiple security measures:

• Path validation - Prevents path traversal attacks

• Symlink protection - Blocks symlink escape attempts

• Input validation - All inputs validated with Zod schemas

• Reserved name blocking - Prevents system file conflicts

See SECURITY.md for details.

Inspiration

This project is inspired by mcp-obsidian.

License

MIT