Obsidian MCP Server

A custom Model Context Protocol (MCP) server for Obsidian vault integration. Enables Claude Code (desktop & mobile) to read, write, search, and manage your Obsidian notes with support for future AI workflows and external integrations.

Features

• 🔍 Core Tools: Read, write, search, and list notes

• 🔄 Git-Backed Sync: Automatic version control and multi-device sync

• 📱 Mobile Support: Works with Claude Code on iPhone/Android

• 🔐 Secure Auth: OAuth 2.1 and API key support

• 🔌 Extensible: Drop-in tool system for adding AI workflows and integrations

• 🐳 Docker Ready: Easy deployment to any VPS

📊 Current Status

✅ Completed:

• Obsidian vault created and Git-backed (obsidian-vault)

• MCP server built and tested locally

• Environment configuration working

• Bug fix: Added dotenv package for proper .env loading

• Server running successfully on localhost:3000

🚧 Next Steps:

• Docker Compose setup for multi-project VPS deployment

• Deploy to Hetzner CPX31 (8GB RAM) VPS

• Configure for remote access (mobile + desktop)

👉 See NEXT-STEPS.md for detailed deployment plan and VPS setup instructions.

Quick Start

Prerequisites

• Node.js 20+

• Git

• Obsidian vault in a Git repository

Installation

# Clone the repository
git clone https://github.com/yourusername/obsidian-mcp-server.git
cd obsidian-mcp-server

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Run in development mode
npm run dev

# Or build and run in production
npm run build
npm start

Configuration

Create a .env file based on .env.example:

GIT_REPO_URL=https://github.com/yourusername/your-vault.git
GIT_BRANCH=main
GIT_TOKEN=ghp_your_token_here
API_KEY=your_secure_api_key

Available Tools

Core Tools

• read_note - Read note content and frontmatter

• write_note - Create or update notes

• search_notes - Full-text search across vault

• list_notes - List files with optional filtering

Future Extensions (Add as needed)

• AI workflows (summarization, tagging, templates)

• Calendar integrations

• Task management integrations

• Custom automations

Deployment

Docker (Recommended)

docker build -t obsidian-mcp .
docker run -p 3000:3000 --env-file .env obsidian-mcp

Hetzner VPS

See docs/deployment.md for detailed deployment instructions.

Extending the Server

To add new tools, create a new file in src/tools/:

import { BaseTool } from './base.tool.js';

export class MyCustomTool extends BaseTool {
  name = 'my_custom_tool';
  description = 'Does something custom';

  inputSchema = {
    type: 'object',
    properties: {
      param: { type: 'string' }
    }
  };

  async execute(params: { param: string }) {
    // Your custom logic here
    const content = await this.vault.read(params.param);
    return { success: true, content };
  }
}

The tool will be automatically discovered and registered.

License

MIT

Contributing

This is a personal project, but suggestions and improvements are welcome!