SimplyAISolution/Obsidian-MCP-Server

Obsidian MCP Server

🔗 Model Context Protocol (MCP) server for Obsidian integration

Enables AI assistants to read, search, and interact with your Obsidian vault through secure, standardized protocols.

Features

• 🔒 Secure vault access with path validation
• 📝 Markdown file reading with metadata extraction
• 🔍 Search capabilities across vault contents
• ⚡ High performance with efficient file handling
• 🛡️ Security-first design with input validation

Quick Start

# Install dependencies
npm install

# Set up your vault path
cp .env.example .env
# Edit .env with your vault path

# Start the server
npm run dev

Installation

Prerequisites

• Node.js 18.0.0 or higher
• An existing Obsidian vault

Setup

1. Clone the repository:

   git clone https://github.com/SimplyAISolution/Obsidian-MCP-Server.git
   cd Obsidian-MCP-Server
   

2. Install dependencies:

   npm install
   

3. Configure environment:

   cp .env.example .env
   

   Edit .env and set your vault path:

   VAULT_PATH=/path/to/your/obsidian/vault
   

4. Build the project:

   npm run build
   

Usage

Development Mode

npm run dev

Production Mode

npm run build
npm start

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Code Quality

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Type checking
npm run typecheck

Configuration

The server can be configured through environment variables:

API Reference

Resources

List Resources

{
  "method": "resources/list",
  "params": {}
}

Read Resource

{
  "method": "resources/read",
  "params": {
    "uri": "obsidian://path/to/file.md"
  }
}

Security

• Path Traversal Protection: All file paths are validated to prevent directory traversal attacks
• File Extension Filtering: Only allowed file extensions can be accessed
• File Size Limits: Large files are rejected to prevent resource exhaustion
• Input Validation: All inputs are validated using Zod schemas

Development

Project Structure

src/
├── handlers/           # Request handlers
│   └── vault.ts       # Vault-specific handlers
├── utils/             # Utility functions
│   ├── logger.ts      # Logging utility
│   └── security.ts    # Security utilities
├── types/             # Type definitions
│   └── config.ts      # Configuration types
├── config.ts          # Configuration management
├── server.ts          # MCP server implementation
└── index.ts           # Main entry point

tests/
├── unit/              # Unit tests
├── integration/       # Integration tests
└── fixtures/          # Test fixtures

Contributing

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

License

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

Support

If you encounter any issues or have questions:

1. Check the
2. Search existing issues
3. Create a new issue with detailed information

Roadmap

• Advanced search functionality
• File writing capabilities
• Plugin integration
• Batch operations
• Real-time file watching
• Enhanced metadata extraction