内容
# local-obsidian-mcp
A local [Model Context Protocol](https://modelcontextprotocol.io) server that gives Claude read and write access to your Obsidian vaults — no cloud sync, no plugins, no API keys.
## What it does
Exposes five MCP tools Claude can call:
| Tool | Description |
|------|-------------|
| `list_notes` | Lists all `.md` notes across your vaults (optionally filtered by vault name) |
| `read_note` | Reads the full content of a specific note by path |
| `search_notes` | Searches note titles and optionally content by keyword (case-insensitive) |
| `create_note` | Creates a new note in a vault; fails if note already exists |
| `commit_vault` | Stages all changes and commits them in a git-tracked vault |
Ask things like:
- *"What notes do I have about machine learning?"*
- *"Read my note on project planning."*
- *"Search my work vault for anything mentioning 'Q3 goals'."*
- *"Create a note called 'meeting-2026-04-30' with these action items."*
- *"Commit the notes you just created with a meaningful message."*
## Prerequisites
- [Node.js](https://nodejs.org) v18+
- [Claude Desktop](https://claude.ai/download) or [Claude Code](https://claude.ai/code)
## Installation
```bash
git clone https://github.com/YOUR_USERNAME/local-obsidian-mcp.git
cd local-obsidian-mcp
npm install
npm run build
```
## Configuration
### 1. Add your vaults
Edit `vaults.json` in the project root:
```json
{
"vaults": [
{
"name": "personal",
"path": "/absolute/path/to/your/obsidian/vault"
},
{
"name": "work",
"path": "/absolute/path/to/another/vault"
}
]
}
```
Use the **absolute path** to each vault folder (the folder Obsidian opens, not a subfolder).
### 2. Connect to Claude Desktop
Add this to your Claude Desktop config file:
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/absolute/path/to/local-obsidian-mcp/dist/index.js"]
}
}
}
```
Restart Claude Desktop after saving.
### 3. Connect to Claude Code
Run this in the project directory:
```bash
claude mcp add obsidian node /absolute/path/to/local-obsidian-mcp/dist/index.js
```
Or add manually to `.claude/settings.json`:
```json
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/absolute/path/to/local-obsidian-mcp/dist/index.js"]
}
}
}
```
## Development
```bash
npm run dev # watch mode — recompiles on save
npm run build # one-off build
npm start # run the compiled server directly
```
## Project structure
```
src/
index.ts # MCP server, tool handlers
vault.ts # filesystem ops, git commit
config.ts # loads vaults.json
types.ts # shared TypeScript interfaces
scripts/
git-commit-vault.sh # shell script wrapping allowed git ops
vaults.json # your vault paths (gitignored if you add personal paths)
```
### `commit_vault` prerequisites
Vaults must be git repositories (`git init` inside the vault folder). The tool runs `git add -A && git commit` — no push, no other git access.
## Privacy
Everything runs locally. No data leaves your machine. Claude reads your notes only when you ask it to, via the tools above.
## Contributing
Issues and PRs welcome. This is an early-stage project — if you hit a bug or want a feature open an issue.
## License
MIT
