ObsidianCliMcp
MCP server that exposes the Obsidian CLI as structured tools for AI agents. Built with Go 1.26 and mcp-go.
Prerequisites
- Go 1.26+
- Obsidian 1.12.0+ with CLI enabled (
Settings → General → Command line interface) obsidianbinary in PATH (verify withwhich obsidian)
Installation
go install (recommended)```bash
go install github.com/mitasych/obsidian-cli-mcp@latest
### Build from source```bash
git clone https://github.com/mitasych/obsidian-cli-mcp
cd obsidian-cli-mcp
go build -o obsidian-cli-mcp .
Usage
Claude Desktop
Add to ~/.config/claude/claude_desktop_config.json:```json
{
"mcpServers": {
"obsidian-cli-mcp": {
"command": "/absolute/path/to/obsidian-cli-mcp"
}
}
}
### Claude Code```bash
claude mcp add obsidian ~/go/bin/obsidian-cli-mcp
Or add manually to ~/.claude.json:```json
{
"mcpServers": {
"obsidian-cli-mcp": {
"command": "/absolute/path/to/obsidian-cli-mcp"
}
}
}
### Custom binary path
If `obsidian` is not in PATH, set the `OBSIDIAN_PATH` environment variable:```json
{
"mcpServers": {
"obsidian-cli-mcp": {
"command": "/absolute/path/to/obsidian-cli-mcp",
"env": {
"OBSIDIAN_PATH": "/usr/bin/obsidian"
}
}
}
}
Custom timeout
Each tool call runs the obsidian CLI with a 30-second timeout by default. Launching Obsidian cold (when it is not already running) can take longer; raise the limit with OBSIDIAN_TIMEOUT. It accepts a Go duration string (45s, 2m) or a bare number of seconds (60):```json
{
"mcpServers": {
"obsidian-cli-mcp": {
"command": "/absolute/path/to/obsidian-cli-mcp",
"env": {
"OBSIDIAN_TIMEOUT": "60s"
}
}
}
}
## Tools
| Tool | Description |
|------|-------------|
| `note_read` | Read note content by name or vault-relative path |
| `note_create` | Create a new note with optional template and content |
| `note_append` | Append content to an existing note |
| `note_prepend` | Prepend content to an existing note |
| `vault_search` | Full-text search across the vault (JSON output) |
| `files_list` | List files with optional folder/extension filters |
| `property_set` | Set a frontmatter property on a note |
| `tags_list` | List tags in the vault (JSON output) |
### Parameters
Tools accept `file` (resolved like wikilinks) or `path` (exact vault-relative path) to target notes. Key parameters per tool:
- **note_read**: `fileOrPath` (required)
- **note_create**: `name` (required), `path`, `content`, `template`, `overwrite`
- **note_append / note_prepend**: `file` or `path`, `content` (required)
- **vault_search**: `query` (required), `path`, `limit`, `case`
- **files_list**: `folder`
- **property_set**: `name` (required), `value` (required), `type`, `file` or `path`
- **tags_list**: `file`, `path`, `counts`, `total`
## Tests```bash
go test ./...
Test MCP with MCP inspector
MCP inspector```
npx @modelcontextprotocol/inspector
## Project Structure```
├── main.go # Entry point: MCP server init + stdio transport
├── internal/
│ ├── cli/
│ │ ├── runner.go # exec.Command wrapper with context timeout
│ │ └── runner_test.go
│ └── tools/
│ ├── tools.go # Tool registry (RegisterAll)
│ ├── notes.go # note_read, note_create, note_append, note_prepend
│ ├── search.go # vault_search
│ ├── files.go # files_list
│ ├── properties.go # property_set
│ └── tags.go # tags_list
└── DEVELOPMENT.md # Architecture and design decisions
License
MIT
