mcpvault — Claude MCP 必备工具中文教程

Prerequisites

• Node.js runtime (v18.0.0 or later)
• An Obsidian vault (local directory with .md, .markdown, .txt, .base, or .canvas files)
• MCP-compatible AI client (Claude Desktop, ChatGPT Desktop, Claude Code, etc.)

Installation

Install globally for easier access

npm install -g @modelcontextprotocol/inspector

Quick Start (5 minutes)

1. Install Node.js runtime:

   # Download from https://nodejs.org (v18.0.0 or later)
   # or use a package manager like nvm, brew, apt, etc.
   

1. Test the server:

If using the published package:

   npx @modelcontextprotocol/inspector npx @bitbonsai/mcpvault@latest /path/to/your/vault
   

1. Configure your AI client:

Claude Desktop - Copy this to claude_desktop_config.json:

   {
     "mcpServers": {
       "obsidian": {
         "command": "npx",
         "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"]
       }
     }
   }
   

Claude Code - Copy this to ~/.claude.json:

   {
     "mcpServers": {
       "obsidian": {
         "command": "npx",
         "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"],
         "env": {}
       }
     }
   }
   

OpenCode - Copy this to ~/.config/opencode/opencode.json

   {
     "mcp": {
       "obsidian": {
         "type": "local",
         "command": [
           "npx",
           "@bitbonsai/mcpvault@latest",
           "/path/to/your/vault/"
         ],
         "enabled": true
       }
     }
   }
   

Replace /path/to/your/vault with your actual Obsidian vault path.

For other platforms, see detailed configuration guides below.

4. Test with your AI: - "List files in my Obsidian vault" - "Read my note called 'project-ideas.md'" - "Create a new note with today's date"

Success indicators: Your AI should be able to list files and read notes from your vault.

Usage

Examples

Ask your AI assistant about your notes:

• "What files are in my Obsidian vault?"
• "Read my note called 'project-ideas.md'"
• "Show me all notes with 'AI' in the title"

Have your AI assistant help with note management:

• "Create a new note called 'meeting-notes.md' with today's date in the frontmatter"
• "Append today's journal entry to my daily note"
• "Prepend an urgent task to my todo list"
• "Add the tags 'project' and 'urgent' to my task note"
• "List all tags in my research note"
• "Remove the 'draft' tag from my completed article"
• "List all markdown files in my 'Projects' folder"
• "Delete the old draft note 'draft-ideas.md' (with confirmation)"

Advanced Use Cases:

• Knowledge Synthesis: "Summarize all my research notes tagged with 'machine-learning' from the last month"
• Project Management: "Update the status in all project notes to 'completed' and add today's date"
• Content Analysis: "Find all notes that mention 'API design' and create a comprehensive guide"
• Smart Tagging: "Review my untagged notes and suggest appropriate tags based on content"

AI Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

Single Vault:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/Users/yourname/Documents/MyVault"
      ]
    }
  }
}

Multiple Vaults:

{
  "mcpServers": {
    "obsidian-personal": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/Users/yourname/Documents/PersonalVault"
      ]
    },
    "obsidian-work": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/Users/yourname/Documents/WorkVault"
      ]
    }
  }
}

Configuration File Locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

You can also access this through Claude Desktop → Settings → Developer → Edit Config

ChatGPT Desktop

Requirements: ChatGPT Enterprise, Education, or Team subscription (not available for individual Plus users)

ChatGPT uses MCP through Deep Research and developer mode. Configuration is done through the ChatGPT interface:

1. Access ChatGPT developer mode (beta feature)
2. Configure MCP servers through the built-in MCP client
3. Create custom connectors for your organization

Note: ChatGPT Desktop's MCP integration is currently limited to enterprise subscriptions and uses a different setup process than file-based configuration.

Claude Code

Claude Code uses .claude.json configuration file:

User-scoped (recommended): Edit ~/.claude.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"],
      "env": {}
    }
  }
}

Project-scoped: Edit .claude.json in your project or add to the projects section:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "obsidian": {
          "command": "npx",
          "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"]
        }
      }
    }
  }
}

Using Claude Code CLI:

claude mcp add obsidian --scope user npx @bitbonsai/mcpvault /path/to/your/vault

Goose Desktop

On Goose Desktop settings, click Add custom extension, and on the command field add:

npx @bitbonsai/mcpvault@latest /path/to/your/vault

Other MCP-Compatible Clients (2025)

Confirmed MCP Support:

• IntelliJ IDEA 2025.1+ - Native MCP client support
• Cursor IDE - Built-in MCP compatibility
• Windsurf IDE - Full MCP integration
• Zed, Replit, Codeium, Sourcegraph - In development
• Microsoft Copilot Studio - Native MCP support with one-click server connections

Most modern MCP clients use similar JSON configuration patterns. Refer to your specific client's documentation for exact setup instructions.

API Methods

Troubleshooting