obsidian

This Obsidian MCP Server enables LLMs such as Claude, ChatGPT, and other agents to interact with an Obsidian vault that is stored in git. The server clones or pulls your vault, exposes a rich set of tools to read, write, organize, and search notes, and then commits changes back to the repository so your Obsidian clients can synchronize. It supports multiple tool categories including File Operations (read, create, edit, delete, move, append, patch), Directory Operations (create directories, list files), Search (fuzzy and exact matching), Tag Management (add, remove, rename), and Journal Logging (auto-log LLM activity). Deployment options include local Docker/Claude Desktop usage, HTTP access for remote clients, and an AWS Lambda option for serverless operation with DynamoDB for sessions. To use the Docker-based setup via Claude Desktop, you mount your environment file containing vault details and token and then configure Claude to start the MCP server via Docker. For npm-based usage, you install dependencies, configure credentials, and point Claude Desktop to run the npm dev script to start the HTTP or stdio mode as needed.

Prerequisites:

• Docker installed on your machine (recommended) or Node.js 22+ with npm if you prefer npm-based setup.
• A git-backed Obsidian vault (repository) and a Git personal access token.
• Basic familiarity with editing a .env file to configure vault details and credentials.

Installation steps (Docker-based):

1. Create and configure your environment file (example):

   • Clone the repo and create obsidian-mcp.env with required values like VAULT_REPO, VAULT_BRANCH, and GIT_TOKEN.
   • Example: VAULT_REPO=https://github.com/yourname/your-vault.git VAULT_BRANCH=main GIT_TOKEN=your_token_here

2. Run the server with Docker (example): docker run -i --rm
   -v "/ABSOLUTE/PATH/TO/obsidian-mcp.env:/app/.env"
   ghcr.io/eddmann/obsidian-mcp:latest stdio

3. Alternatively, use the Claude Desktop/NPM path by following the repository’s Quick Start notes and configuring Claude to point to the npm dev script if you prefer npm-based deployment.

Installation steps (npm-based):

1. Clone the repository and install dependencies: git clone https://github.com/eddmann/obsidian-mcp cd obsidian-mcp npm install

2. Configure credentials: cp .env.example .env Edit .env with VAULT_REPO, VAULT_BRANCH, GIT_TOKEN, and any OAuth credentials if using HTTP/Cloud deployments.

3. Start the HTTP or stdio server (examples): npm run dev:http or npm run dev:stdio

Note: For AWS Lambda deployment, follow the repository’s Deployment Guide to set up CDK deployments and configure environment variables in the Lambda function.

Tips and common issues:

• Ensure your vault repository is initialized as a Git repository and is push-enabled with a remote URL reachable by the server.
• When using Docker, ensure the path to the env file is absolute inside the host and that the container has access to that path.
• For OAuth and HTTP mode, you will need to provide OAuth client credentials, tokens, and a base URL as described in the Deployment Guide.
• If you encounter permission issues on file writes, verify that the container user has access to the mounted repository and environment file.
• The npm-based approach is convenient if you want to run in environments where Docker is restricted; it uses the same underlying MCP server logic.
• The server supports multiple deployment modes (stdio for local Claude Desktop, http for remote access, and Lambda for serverless use). Choose the mode that matches your workflow and ensure the appropriate config in Claude or your HTTP client.
• Keep your vault up-to-date by scheduling periodic pulls or enabling obsidian-git syncing to minimize conflicts with LLM edits.