Skip to content

Latest commit

 

History

History
314 lines (242 loc) · 5.86 KB

CLAUDE_DESKTOP_SETUP.md

File metadata and controls

314 lines (242 loc) · 5.86 KB

Claude Desktop Setup Guide

Step-by-Step Instructions

1. Build the MCP Server

First, make sure your server is built:

cd ~/Projects/obsidian-mcp
npm install
npm run build

This creates the compiled server in dist/index.js.

2. Create Your Vault Configuration

Create obsidian-mcp.json in the project root:

{
  "vaults": [
    {
      "name": "documents",
      "type": "local",
      "path": "~/Documents"
    }
  ]
}

Important: Use the ABSOLUTE path to your vault folder!

3. Configure Claude Desktop

Claude Desktop's config location depends on your OS:

  • Linux: ~/.config/Claude/claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

For you on Linux, edit:

nano ~/.config/Claude/claude_desktop_config.json

Or create it if it doesn't exist:

mkdir -p ~/.config/Claude

4. Add MCP Server Configuration

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": [
        "~/Projects/obsidian-mcp/dist/index.js"
      ]
    }
  }
}

Key Points:

  • Use ABSOLUTE paths (not ~/ or $HOME)
  • The config file is in your home directory, NOT in the project
  • The server will read obsidian-mcp.json from its own directory

5. Alternative: Using Environment Variables

If you prefer environment variables over the config file:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": [
        "~/Projects/obsidian-mcp/dist/index.js"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "~/Documents",
        "OBSIDIAN_VAULT_NAME": "documents"
      }
    }
  }
}

6. Restart Claude Desktop

After editing the config:

  1. Quit Claude Desktop completely (not just close the window)
    • On Linux: pkill -9 claude or use your system tray to quit
  2. Restart Claude Desktop
  3. The MCP server will auto-start when Claude launches

7. Verify Connection

In Claude Desktop, you should see:

  1. MCP icon/indicator showing the server is connected
  2. Available tools - Claude will mention it has access to Obsidian tools
  3. Try asking: "What vaults do you have access to?"

8. Test with a Simple Query

Try these prompts:

"Search my Obsidian vault for notes about projects"

"Show me vault statistics"

"List all tags in my vault"

"Create a new note called 'Test.md' with the content 'Hello World'"

Troubleshooting

Claude Desktop doesn't show the MCP server

Check the logs:

# Linux
tail -f ~/.config/Claude/logs/mcp*.log

# Or check Claude's developer console
# Menu: View > Toggle Developer Tools > Console tab

Common issues:

  1. ❌ Used relative paths instead of absolute paths
  2. ❌ dist/index.js doesn't exist (run npm run build)
  3. ❌ obsidian-mcp.json is missing or has wrong vault path
  4. ❌ Didn't restart Claude Desktop after config change

Server starts but can't access vault

Check:

  1. Vault path is correct and absolute
  2. Path exists: ls -la ~/Documents
  3. You have read permissions: ls -la ~/Documents/*.md

View server logs: The server logs go to stderr, which Claude Desktop captures. Check the developer console.

Node version issues

Make sure you have Node.js 18+ installed:

node --version  # Should be v18.0.0 or higher

If using nvm:

nvm use 22
which node  # Get the full path

Then use the full node path in your config:

{
  "mcpServers": {
    "obsidian": {
      "command": "~/.nvm/versions/node/v22.x.x/bin/node",
      "args": ["~/Projects/obsidian-mcp/dist/index.js"]
    }
  }
}

Complete Example Configuration

Your obsidian-mcp.json

{
  "vaults": [
    {
      "name": "documents",
      "type": "local",
      "path": "~/Documents"
    }
  ],
  "server": {
    "name": "obsidian-mcp-server",
    "version": "1.0.0"
  }
}

Your ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": [
        "~/Projects/obsidian-mcp/dist/index.js"
      ]
    }
  }
}

Multiple Vaults Example

If you have multiple Obsidian vaults:

obsidian-mcp.json

{
  "vaults": [
    {
      "name": "personal",
      "type": "local",
      "path": "~/Documents/PersonalVault"
    },
    {
      "name": "work",
      "type": "local",
      "path": "~/Documents/WorkVault"
    }
  ]
}

Then in Claude, you can specify which vault:

"Search the 'work' vault for project notes"
"Create a note in the 'personal' vault"

What You Can Do After Setup

Once connected, Claude will have access to these capabilities:

📝 Note Operations

  • Read, create, update, delete notes
  • Search by content, tags, folders
  • Parse markdown and frontmatter

🔗 Knowledge Graph

  • Analyze relationships between notes
  • Find related notes
  • Suggest potential links
  • Identify orphan notes

📊 Analytics

  • Vault statistics
  • Tag usage analysis
  • Link density

🎨 Canvas Support

  • Read and create canvas files
  • Add nodes and edges
  • Visualize connections

📅 Periodic Notes

  • Create daily/weekly/monthly/yearly notes
  • Template support

🔍 Dataview-Style Queries

  • SQL-like querying
  • Filter by metadata
  • Group and sort results

Advanced: NPM Global Installation

If you want to install globally:

cd ~/Projects/obsidian-mcp
npm install -g .

Then in Claude config:

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp"
    }
  }
}

Need Help?

  1. Check Claude Desktop developer console for errors
  2. Verify dist/index.js exists and is executable
  3. Test the server manually: node dist/index.js (it should wait for input)
  4. Check file permissions on your vault folder
  5. Make sure all paths are absolute, not relative