Obsidian MCP Server

A TypeScript-based Model Context Protocol (MCP) server that provides secure access to Obsidian vaults for AI assistants. Run locally with support for multiple vaults, configurable file access, and comprehensive markdown operations.

Features

• Multi-Vault Support: Access multiple Obsidian vaults with individual configuration
• Secure File Operations: Path validation, size limits, and configurable scope restrictions
• YAML Frontmatter: Parse and manipulate frontmatter in markdown files
• File Type Filtering: Support for .md, .png, .pdf, and configurable additional extensions
• Content Search: Basic text search across markdown files with context
• Cross-Platform: Works on Windows, macOS, and Linux

Installation

Global Installation (Recommended)

npm install -g obsidian-mcp-server

Local Development

git clone <repository-url>
cd obsidian-mcp-server
npm install
npm run build

Configuration

Create a config.json file to define your vault settings:

{
  "vaults": [
    {
      "name": "main",
      "path": "/path/to/your/obsidian-vault",
      "allowedPaths": [
        "notes/",
        "projects/"
      ]
    },
    {
      "name": "work",
      "path": "/path/to/work-vault"
    }
  ],
  "fileExtensions": [
    ".md",
    ".png", 
    ".pdf",
    ".txt"
  ],
  "maxFileSize": "10MB",
  "logLevel": "info",
  "logToFile": true,
  "verifyVaultsOnStartup": true
}

Configuration Options

• vaults: Array of vault configurations
  • name: Unique identifier for the vault
  • path: Absolute path to the vault directory
  • allowedPaths: (Optional) Array of subdirectory paths to restrict access
• fileExtensions: Array of allowed file extensions (default: .md, .png, .pdf)
• maxFileSize: Maximum file size for reading (default: 10MB)
• logLevel: Logging verbosity (default: info) - options: error, warn, info, debug
• logToFile: Enable file-based logging (default: true) - creates logs in logs/ directory
• verifyVaultsOnStartup: Verify vault access and log top folders on startup (default: true)

Usage

Command Line

# With config file
obsidian-mcp-server --config /path/to/config.json

# With config file and specific log level
obsidian-mcp-server --config /path/to/config.json --log-level debug

# With default configuration (uses current directory)
obsidian-mcp-server

MCP Client Integration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp-server",
      "args": ["--config", "/path/to/your/config.json"]
    }
  }
}

If running locally

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/index.js", "--config", "/path/to/obsidian-mcp-server/config/config.json"]
    }
  }
}

MCP Tools

The server provides the following tools for AI assistants:

read_file

Read content from markdown files or metadata from binary files.

{
  "vault_name": "main",
  "file_path": "notes/example.md",
  "include_content": true,
  "include_frontmatter": true
}

write_file

Create or update markdown files with optional frontmatter.

{
  "vault_name": "main",
  "file_path": "notes/new-note.md",
  "content": "# New Note\n\nContent here...",
  "frontmatter": {
    "title": "My New Note",
    "tags": ["example", "new"]
  },
  "create_directories": true
}

list_files

List files in vault directories with filtering.

{
  "vault_name": "main",
  "directory_path": "notes",
  "include_metadata": false
}

search_content

Search for text across markdown files.

{
  "vault_name": "main",
  "query": "search term",
  "directory_path": "notes",
  "case_sensitive": false,
  "whole_word": false,
  "max_results": 50
}

get_metadata

Get file metadata including frontmatter without full content.

{
  "vault_name": "main",
  "file_path": "notes/example.md"
}

Development

Scripts

# Build the project
npm run build

# Development with watch mode
npm run dev

# Run tests
npm run test
npm run test:watch
npm run test:coverage

# Linting and formatting
npm run lint
npm run lint:fix
npm run format
npm run format:check

Project Structure

src/
├── config/           # Configuration loading and validation
├── obsidian/         # Vault operations and metadata parsing
├── tools/            # MCP tool implementations
├── server.ts         # Main MCP server
└── index.ts          # CLI entry point

Testing

The project includes comprehensive tests:

• Unit tests for all core functionality
• Integration tests with mock vaults
• 90%+ test coverage target
• Cross-platform compatibility tests

Run tests:

npm test                # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # With coverage report

Security

• Path Validation: Prevents directory traversal attacks
• Scope Restriction: Configurable allowed paths per vault
• File Size Limits: Prevents reading of excessively large files
• Extension Filtering: Only processes specified file types
• Read-Only Binary Files: Binary files return metadata only

Troubleshooting

Common Issues

1. Permission Errors: Ensure the server has read/write access to vault directories
2. Path Issues: Use absolute paths in configuration
3. File Size Errors: Adjust maxFileSize if needed for larger files
4. Extension Errors: Add required extensions to fileExtensions array

Debug Mode

Enable detailed logging:

# Using command line option
obsidian-mcp-server --config config.json --log-level debug

# Or set in config.json
{
  "logLevel": "debug",
  "vaults": [...],
  ...
}

Available log levels: error, warn, info, debug

Logging Features

The server uses Winston for comprehensive logging with the following features:

• Console Logging: All logs output to stderr (colorized for better readability)
• File Logging: Persistent logs stored in logs/ directory
  • combined.log: All log levels (rotated, max 5MB, keeps 5 files)
  • error.log: Error-level logs only (rotated, max 5MB, keeps 5 files)
  • exceptions.log: Uncaught exceptions
  • rejections.log: Unhandled promise rejections

Log Structure: Each log entry includes timestamp, level, message, and structured metadata Performance Timing: Operations include execution timing for performance monitoring Operation Tracking: Each tool execution gets a unique operation ID for tracing

Disable file logging by setting "logToFile": false in your configuration.

Vault Verification

On startup, the server automatically verifies vault access and logs the top 10 folders (by file count) in each vault. This helps confirm that:

• Vault paths are accessible
• File permissions are correct
• Expected content structure is present

Example verification output:

[INFO] Starting vault verification process
[INFO] Verifying vault access {"vaultName":"main","path":"/path/to/vault"}
[INFO] Top folders in vault {"vaultName":"main","folders":[
  {"name":"notes","path":"notes","fileCount":45},
  {"name":"projects","path":"projects","fileCount":23},
  {"name":"archive","path":"archive","fileCount":12}
]}
[INFO] Vault verification completed {"vaultName":"main","foldersFound":8,"durationMs":156}

Disable verification by setting "verifyVaultsOnStartup": false in your configuration.

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Support

• GitHub Issues
• MCP Protocol Documentation