Obsidian MCP Server

🚀 Obsidian MCP Server

Obsidian MCP Server is a functional module based on Model Context Protocol, designed to enable powerful file and content management capabilities within an Obsidian vault. By leveraging tool resources, this server can perform complex text processing and content operations.

🚀 Quick Start

📦 Installation

Install the MCP Server

npm install obsidian-mcp-server

Configure the MCP Server

1. Add the following configuration to package.json:

"mcp_server": {
  "vault_root": "./vault",  // Specify the root directory path of the vault
  "port": 3001,             // Optional, default port is 3001
  "log_level": "info"       // Optional, log levels: debug, info, warning, error
}

2. Start the server

npm start

💻 Usage Examples

Basic Usage

If you want to clone the repository, install dependencies, configure server parameters, and start the server, you can follow these steps:

1. Clone the repository

git clone https://github.com/mcptoolkit/obsidian-mcp-server.git

2. Install dependencies

cd obsidian-mcp-server
npm install

3. Configure server parameters Fill in the following information in the config.json file:

{
  "vault_root": "./vault",  // Specify the root directory of the vault
  "port": 3001,             // Optional, default port is 3001
  "log_level": "info"       // Optional, log levels: debug, info, warning, error
}

4. Start the server

npm start

✨ Features

File Management

• List Files: List all files in a specified directory or the root directory of the vault.
• Read File Content: Return the content of a file at a specified path.
• Create/Update File: Support atomic operations to ensure the safety and reliability of file writing processes.

Content Search

• Simple Text Search: Find keywords in a specified file and return the context.
• Complex Search (JsonLogic): Filter files and directories based on custom JsonLogic expressions.
• Tag Management: Retrieve all tag information in the vault or a specific directory.

Attribute Management

• Query File Attributes: Get the metadata of a specified file, including title, author, type, etc.
• Update File Attributes: Support custom field updates and automatically maintain timestamp fields.

📚 Documentation

Tool Interfaces

File Operation Tools

// List all files in the vault
obsidian_list_files_in_vault: {
}

// List files in a specified directory
obsidian_list_files_in_dir: {
  dirpath: string; // Path relative to the root directory of the vault
}

// Get file content
obsidian_get_file_contents: {
  filepath: string; // Path relative to the root directory of the vault
}

Search Operation Tools

// Find text in a file and return the context
obsidian_find_in_file: {
  query: string,
  contextLength?: number  // Default context length is 10
}

// Perform a complex search using a JsonLogic expression
obsidian_complex_search: {
  query: JsonLogicQuery
  // Example:
  // Search by tag: "{"in": ["#mytag", {"var": "frontmatter.tags"}]}"
  //
  // Search by directory: "{"glob": ["docs/*.md", {"var": "path"}]}"
  //
  // Combine conditions: "{"and": [
  //   {"glob": ["*.md", {"var": "path"}]},
  //   {"in": ["#mytag", {"var": "frontmatter.tags"}]}
  // ]}"
}

Content Modification Tools

// Append content to the end of a file
obsidian_append_content: {
  filepath: string,  // Path relative to the root directory of the vault
  content: string    // Content to be appended
}

// Replace file content
obsidian_patch_content: {
  filepath: string,  // Path relative to the root directory of the vault
  content: string    // New content
}

Attribute Management Tools

// Get file metadata
obsidian_get_file_metadata: {
  filepath: string   // Path relative to the root directory of the vault
}

// Update file attributes
obsidian_update_file_properties: {
  filepath: string,  // Path relative to the root directory of the vault
  properties: {      // Attributes to be updated
    [key: string]: any
  }
}

Core Function Examples

File Management Module

• List Files

const result = await client.call("obsidian_list_files_in_dir", { dirpath: "./" });
console.log(result);

• Read File Content

const content = await client.call("obsidian_get_file_contents", { filepath: "notes/README.md" });
console.log(content);

Content Search Module

• Simple Text Search

const result = await client.call("obsidian_find_in_file", {
  filepath: "notes/index.md",
  query: "hello"
});
console.log(result);

• Complex Search (JsonLogic)

const result = await client.call("obsidian_complex_search", {
  query: "{ \"and\": [\n" +
         "  { \"glob\": [\"docs/*.md\", { \"var\": \"path\" } ] },\n" +
         "  { \"in\": [=\"#todo\", { \"var\": \"frontmatter.tags\" } ] }\n" +
         "] }"
});
console.log(result);

Attribute Management Module

• Query File Attributes

const metadata = await client.call("obsidian_get_file_metadata", { filepath: "notes/todo.md" });
console.log(metadata);

• Update File Attributes

const result = await client.call("obsidian_update_file_properties", {
  filepath: "notes/todo.md",
  properties: {
    priority: "high",
    due_date: "2024-03-15"
  }
});
console.log(result);

Usage Scenarios

Example 1: Automated File Archiving

const { DateTime } = require('luxon');

async function archiveOldFiles() {
  const today = DateTime.local().toISODate();
  const files = await client.call("obsidian_list_files_in_dir", { dirpath: "./old" });
  
  for (const file of files) {
    if (file.lastModified < today) {
      await client.call("obsidian_move_file", {
        from_path: `old/${file.name}`,
        to_path: `archived/${today}/${file.name}`
      });
    }
  }
}

setInterval(archiveOldFiles, 86400000); // Execute once a day

Example 2: Automatic Content Categorization

async function autoCategorize() {
  const files = await client.call("obsidian_list_files_in_dir", { dirpath: "./notes" });
  
  for (const file of files) {
    const content = await client.call("obsidian_get_file_contents", { filepath: `notes/${file.name}` });
    const category = getCategoryFromContent(content);
    
    if (category) {
      await client.call("obsidian_move_file", {
        from_path: `notes/${file.name}`,
        to_path: `${category}/${file.name}`
      });
    }
  }
}

setInterval(autoCategorize, 604800000); // Execute once a week

🔧 Technical Details

Best Practices

• Configuration Management: Ensure that vault_root and the log level are correctly configured for the normal operation of the server.
• Transaction Control: For operations involving file modifications, it is recommended to use transactions to ensure data consistency.
• Permission Control: Set access control policies according to actual needs to prevent unauthorized operations.

Common Issues

• How to handle large files? For large files, it is recommended to process them in chunks or use streaming to improve efficiency.
• What if the server performance is insufficient? You can optimize the code, increase memory, or use more efficient algorithms to improve performance. If a single machine cannot handle the load, consider distributed deployment.
• How to ensure data consistency? When performing file operations, it is recommended to use a transaction mechanism to ensure that each operation either succeeds completely or fails completely, thereby maintaining data consistency.

📄 License

The project is open - source under the MIT license.

Resources

• Official Documentation: Obsidian MCP Server Documentation
• Example Code: GitHub Example Repository

Contribution Guidelines

• Issue Reporting: If you find any issues or bugs, please submit them in Issues.
• Feature Suggestions: You are welcome to propose suggestions for feature enhancements or optimizations. We will carefully consider each reasonable requirement.
• Open - Source Contribution: The project is open - source under the MIT license. You are welcome to fork the repository and submit PRs to improve this tool together.