Obsidian MCP Server

A Model Context Protocol (MCP) server for git-backed Obsidian vaults. Access and manage your notes through Claude, ChatGPT, and other LLMs by syncing changes via git.

Table of Contents

• Overview
• Quick Start
• How It Works
• Prerequisites
• Deployment Options
  • Claude Desktop (Local)
  • ChatGPT & Remote Clients
  • AWS Lambda
• Usage Examples
• Tool Reference
• Resources
• Documentation
• License

Overview

This MCP server provides 18 tools and 1 resource to interact with your Obsidian vault through LLMs:

Tool Categories:

• File Operations (9) - Read, create, edit, delete, move, append, and patch notes
• Directory Operations (3) - Create directories and list files
• Search (1) - Fuzzy search with relevance scoring and exact matching
• Tag Management (4) - Add, remove, rename, and manage tags
• Journal Logging (1) - Auto-log LLM activity to daily journals

Deployment Modes:

• Stdio - Local deployment for Claude Desktop, Cursor
• HTTP - Local/remote with OAuth for ChatGPT, Claude web
• AWS Lambda - Serverless deployment with DynamoDB sessions

Quick Start

Get started with Claude Desktop in 3 steps using Docker:

# 1. Download the example environment file
curl -O https://raw.githubusercontent.com/eddmann/obsidian-mcp/main/.env.example
mv .env.example obsidian-mcp.env

# 2. Edit obsidian-mcp.env with your vault repo and git token
# Required fields:
#   VAULT_REPO=https://github.com/username/vault-repo.git
#   VAULT_BRANCH=main
#   GIT_TOKEN=your_token_here

3. Add to Claude Desktop config:

Restart Claude Desktop and start chatting with your vault!

How It Works

This server is designed for git-backed Obsidian vaults managed by plugins like obsidian-git.

graph LR
    A[Git Repository] -->|1. Clone/Pull| B[MCP Server]
    B -->|2. LLM Modifies| C[Local Vault Copy]
    C -->|3. Auto Commit & Push| A
    A -->|4. Sync| D[Obsidian Clients]

    style B fill:#4a9eff
    style C fill:#7c3aed

Workflow:

1. Server clones/pulls your vault from git
2. LLM makes changes through MCP tools
3. Server automatically commits and pushes changes
4. Your Obsidian clients pull to stay synchronized

This enables LLM access without Obsidian being open, with all changes synchronized via git.

Prerequisites

Deployment Options

Claude Desktop (Local)

Using Docker:

See Quick Start above for the recommended Docker-based setup.

ChatGPT & Remote Clients

Run the server in HTTP mode with OAuth authentication:

Using Docker:

docker run -p 3000:3000 --rm \
  -v "/ABSOLUTE/PATH/TO/obsidian-mcp.env:/app/.env" \
  ghcr.io/eddmann/obsidian-mcp:latest \
  http

Using npm:

# First clone the repo if you haven't already
git clone https://github.com/eddmann/obsidian-mcp
cd obsidian-mcp
npm install

# Configure all environment variables (including OAuth)
cp .env.example .env
# Edit .env

# Run HTTP server
npm run dev:http

Required environment variables:

• All core variables (see .env.example)
• OAuth variables: OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, PERSONAL_AUTH_TOKEN, BASE_URL

See Deployment Guide for detailed configuration and ChatGPT integration.

AWS Lambda

Deploy to AWS Lambda for remote access with DynamoDB session storage:

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

# 2. Install dependencies
npm install

# 3. Configure all environment variables (including OAuth)
cp .env.example .env
# Edit .env

# 4. Deploy to AWS
npm run cdk:deploy

What gets deployed:

• Lambda function (ARM64, 2GB memory, 10GB storage)
• DynamoDB table with TTL-based sessions
• Function URL with CORS enabled
• CloudWatch logs (1-week retention)

Cleanup:

npm run cdk:destroy

See Deployment Guide for complete setup instructions.

Usage Examples

Ask your LLM to interact with your vault using natural language:

Tool Reference

File Operations (9 tools)

Directory Operations (3 tools)

Search (1 tool)

Tag Management (4 tools)

Journal Logging (1 tool)

Resources

MCP resources provide contextual information that LLMs can access on-demand.

Vault README

If your vault contains a README.md file in its root directory, LLMs can access it to understand how your vault is organized.

Documentation

• Tool Reference - Detailed documentation for all 18 tools with usage examples
• Deployment Guide - Complete deployment instructions for all modes
• Git Providers - Setup instructions for GitHub, GitLab, Bitbucket, and self-hosted providers

License

MIT