# Obsidian CLI MCP Server

MCP server that exposes Obsidian vault operations over HTTP. Uses the **obsidian CLI** via subprocess — requires the Obsidian desktop app to be running.

**Placeholders:** Examples use `<project-root>`, `<vault-root>`, and `localhost:3100` — replace with your actual paths and host/port. All examples are generic and safe for public use.

## Prerequisites

- **Obsidian** desktop app installed and running
- **gtimeout** (GNU coreutils): `brew install coreutils` on macOS
- **Python 3.10+**

## Quick Start

```bash
cd <project-root>   # e.g. ~/projects/obsidian-cli-mcp
pip install -r requirements.txt
cp .env.example .env   # edit .env with your vault path
python -m src.server
```

Server listens on `http://localhost:3100/mcp`.

**Dev mode** (auto-restart on file changes):

```bash
make dev
```

**Smoke test** (run all read operations; edit hardcoded paths in `scripts/smoke_test.py` to match your vault):

```bash
python scripts/smoke_test.py
```

## Tools

| Tool                    | Purpose                                        |
| ----------------------- | ---------------------------------------------- |
| `health`                | Check obsidian CLI and vault status            |
| `obsidian_base_query`   | Query .base database files                      |
| `obsidian_base_views`   | List views in a .base file                     |
| `obsidian_read`         | Read a note by name or path                    |
| `obsidian_search`       | Full-text search with context                  |
| `obsidian_search_json`  | Full-text search as JSON                       |
| `obsidian_daily_read`   | Read today's daily note                        |
| `obsidian_daily_append` | Append to today's note (write-gated)           |
| `obsidian_files`        | List files in a folder                         |
| `obsidian_backlinks`    | Notes that link to this note                   |
| `obsidian_links`        | Outgoing links from a note                     |
| `obsidian_tags`         | All tags with counts                           |
| `obsidian_tags_file`    | Tags for a specific file                       |
| `obsidian_properties`   | Frontmatter properties                         |
| `obsidian_create`       | Create a note (write-gated)                    |

## Environment Variables

| Variable                   | Default           | Purpose                                                    |
| -------------------------- | ----------------- | ---------------------------------------------------------- |
| `OBSIDIAN_VAULT_PATH`      | (in `.env`)       | Vault directory (cwd for obsidian CLI); see `.env.example` |
| `OBSIDIAN_VAULT`           | (none)            | Vault name when multiple vaults exist                      |
| `OBSIDIAN_TIMEOUT_SECONDS` | `10`              | Timeout for obsidian CLI (base queries use 30s)            |
| `ALLOW_WRITE_COMMANDS`     | `false`           | Enable create, append, property:set                        |
| `MCP_HOST`                 | `0.0.0.0`         | Bind address                                               |
| `MCP_PORT`                 | `3100`            | Server port                                                |
| `MCP_TRANSPORT`            | `streamable-http` | `stdio` for Cursor command; `streamable-http` for URL      |

## Connect from Continue

Place config at `<vault-root>/.continue/mcpServers/obsidian-cli-mcp.yaml`:

```yaml
name: Obsidian CLI
version: 1.0.0
schema: v1
mcpServers:
  - name: obsidian-cli-mcp
    type: streamable-http
    url: http://localhost:3100/mcp
```

Start the server before using Continue. Or use `cn --mcp http://localhost:3100/mcp`.

## Connect from Cursor

**Option A – Command (recommended)** – Cursor spawns the server; no manual start needed:

```json
{
  "mcpServers": {
    "obsidian-cli-mcp": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "<project-root>",
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}
```

Use your actual project path for `cwd`, or omit it if the project is your workspace root.

**Option B – URL** – Start the server manually first (`python -m src.server`), then add:

```json
{
  "mcpServers": {
    "obsidian-cli-mcp": {
      "url": "http://localhost:3100/mcp"
    }
  }
}
```