Obsidian MCP Server

🚀 Obsidian MCP Server

This is a server that integrates Obsidian with the Model Context Protocol (MCP). It provides a range of features to enhance note - taking and management in Obsidian.

✨ Features

Basic Features

• Create notes using templates.
• Load and update notes.
• Get a list of available templates.
• Manage and search tags.
• Search for files and directories.

Link Management Features (High - Priority Features)

• Create wiki links between notes.
• Detect and assist in fixing broken links.
• Analyze backlinks and understand the graph structure.
• Automatically generate Map of Contents (MOC) notes.

📦 Installation

1. Install dependencies:

   npm install
   

2. Compile TypeScript:

   npm run build
   

3. Set environment variables:

   export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"
   export OBSIDIAN_TEMPLATE_DIR="TEMPLATE"
   

   ⚠️ Important Note

   Replace OBSIDIAN_VAULT_PATH with the actual path to your Obsidian vault.

4. Start the server:

   npm start
   

📚 Documentation

Configuration in Claude Desktop

1. Locate the configuration file:

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

2. Find the project path:

   pwd
   

   Use this command to get the absolute path of the project.

3. Find the Node.js path:

   which node
   

   Use this command to find the path of Node.js.

4. Edit the configuration file: Add the following settings to the configuration file:

   Basic settings:

   {
     "mcpServers": {
       "obsidian": {
         "command": "node",
         "args": ["/path/to/obsidian-mcp-server/dist/server.js"],
         "env": {
           "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault",
           "OBSIDIAN_TEMPLATE_DIR": "TEMPLATE"
         }
       }
     }
   }
   

   Configuration example:

   {
     "mcpServers": {
       "obsidian": {
         "command": "node",
         "args": ["/Users/username/Projects/obsidian-mcp-server/dist/server.js"],
         "env": {
           "OBSIDIAN_VAULT_PATH": "/Users/username/Documents/MyVault",
           "OBSIDIAN_TEMPLATE_DIR": "TEMPLATE"
         }
       }
     }
   }
   

   For troubleshooting (explicitly specify the Node.js path):

   {
     "mcpServers": {
       "obsidian": {
         "command": "/usr/local/bin/node",
         "args": ["/path/to/obsidian-mcp-server/dist/server.js"],
         "env": {
           "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault",
           "OBSIDIAN_TEMPLATE_DIR": "TEMPLATE"
         }
       }
     }
   }
   

   ⚠️ Important Note

   • Replace /path/to/obsidian-mcp-server/dist/server.js with the actual project path.
   • Replace /path/to/your/obsidian/vault with the actual path to your Obsidian vault.
   • Replace /usr/local/bin/node with the Node.js path obtained from which node.

5. Restart Claude Desktop

Configuration in other MCP clients

If you are using other MCP clients, refer to the following settings:

• Command: node /path/to/obsidian-mcp-server/dist/server.js
• Environment variables:
  • OBSIDIAN_VAULT_PATH: Path to the Obsidian vault.
  • OBSIDIAN_TEMPLATE_DIR: Name of the template directory.

💻 Usage Examples

Available Tools

1. create_note_from_template

Create an Obsidian note using a template.

Parameters:

• templateName (required): Name of the template in the TEMPLATE folder (without the .md extension).
• variables (required): Object for replacing variables in the template.
• outputPath (required): Path to save the note (relative to the vault).
• overwrite (optional): Whether to overwrite an existing file (default: false).

2. list_templates

Get a list of available templates in the TEMPLATE folder.

Parameters: None

3. read_note

Load the content of an Obsidian note.

Parameters:

• notePath (required): Path to the note (relative to the vault).

4. update_note

Update the content of an Obsidian note.

Parameters:

• notePath (required): Path to the note (relative to the vault).
• content (required): New content of the note.

5. list_tags

List all tags in the Obsidian vault.

Parameters: None

6. rename_tag

Rename tags in the Obsidian vault in bulk.

Parameters:

• oldTag (required): Old tag name (with or without #).
• newTag (required): New tag name (with or without #).

7. search_files

Search for files and directories in the Obsidian vault.

Parameters:

• searchPath (optional): Path to start the search (relative to the vault, default is the root).
• pattern (optional): Search pattern (part of the file name, default is all).

Link Management Tools (High - Priority Features)

8. link_notes

Create a wiki link between notes.

Parameters:

• sourceNote (required): Path to the source note (relative to the vault).
• targetNote (required): Path to the target note (relative to the vault).
• linkText (optional): Display text (default is the file name).
• insertPosition (optional): Insertion position ('end', 'cursor', or line number, default: 'end').

Functions:

• Check file existence.
• Detect and warn about duplicate links.
• Resolve relative paths.
• Insert in the wiki link format [[target|display text]].

9. find_broken_links

Detect and assist in fixing broken links.

Parameters: None

Functions:

• Support both wiki links [[]] and Markdown links []().
• Provide repair candidates through fuzzy search.
• Consider differences in case, spaces, and special characters.
• Display line numbers and surrounding context.

Return value:

{
  "brokenLinks": [
    {
      "sourceFile": "notes/example.md",
      "linkText": "Missing Note",
      "targetPath": "missing-note",
      "lineNumber": 15,
      "suggestions": ["similar-note", "missing-note-backup"]
    }
  ],
  "totalCount": 1
}

10. analyze_backlinks

Analyze backlinks and understand the graph structure.

Parameters:

• targetNote (required): Path to the note to be analyzed (relative to the vault).

Functions:

• Detect backlinks to the specified note.
• Extract the context around the links.
• Identify related notes.
• Calculate popularity and centrality metrics.

Return value:

{
  "targetNote": "important-concept.md",
  "backlinks": [
    {
      "sourceFile": "notes/research.md",
      "context": "This concept is known as [[important-concept]]",
      "linkType": "wiki"
    }
  ],
  "relatedNotes": ["notes/research.md"],
  "metrics": {
    "popularity": 5,
    "centrality": 0.1
  }
}

11. create_moc

Automatically generate a Map of Contents (MOC) note.

Parameters:

• title (required): Title of the MOC.
• targetPath (required): Path to save the MOC (relative to the vault).
• sourcePattern (optional): Pattern of the target notes (default is all).
• groupBy (optional): Grouping method ('tag', 'folder', 'none', default: 'none').
• includeDescription (optional): Whether to include descriptions (default: false).

Functions:

• Select files through pattern matching.
• Group by tags or folders.
• Automatically extract descriptions from YAML frontmatter.
• Generate the MOC in the wiki link format.

Example of generated MOC:

# Project - Related Notes

*This Map of Contents was automatically generated - 2024-01-15*

## #project
- [[project-planning|Project Planning]] - Specification and design of new features
- [[project-timeline|Project Schedule]] - Development schedule and milestones

## #development  
- [[api-design|API Design]] - Specification of RESTful API
- [[database-schema|Database Design]] - Table structure and relationships

Usage Examples via MCP

Examples of using basic tools

// Create a note from a template
await mcp.callTool('create_note_from_template', {
  templateName: 'meeting-notes',
  variables: {
    title: 'Project Planning Meeting',
    participants: 'Tanaka, Sato, Yamada',
    agenda: 'Discussion on new feature specifications',
    notes: '',
    action_items: ''
  },
  outputPath: 'meetings/2024-01-15-project-planning.md'
});

// Create a link between notes
await mcp.callTool('link_notes', {
  sourceNote: 'meetings/2024-01-15-project-planning.md',
  targetNote: 'projects/new-feature.md',
  linkText: 'New Feature Project',
  insertPosition: 'end'
});

Examples of using link management tools

// Detect broken links
const brokenLinks = await mcp.callTool('find_broken_links');

// Analyze backlinks
const backlinks = await mcp.callTool('analyze_backlinks', {
  targetNote: 'concepts/important-concept.md'
});

// Create a Map of Contents
await mcp.callTool('create_moc', {
  title: 'Project - Related Notes',
  targetPath: 'index/project-moc.md',
  sourcePattern: 'project',
  groupBy: 'tag',
  includeDescription: true
});

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.