# Obsidian MCP Server

A Model Context Protocol (MCP) server for Obsidian vault operations. Works with any MCP-compatible client including Claude Desktop, Cursor, Windsurf, and VS Code.

## Features

- **Full Vault Access**: Read, write, search, and delete notes
- **Link Navigation**: Get outgoing links and backlinks for any note
- **Tag Management**: List all tags, find notes by tag
- **Flexible Search**: Search by content, title, tags, or folder
- **Two Transports**: Stdio (local) or Streamable HTTP (remote)
- **Modern MCP**: Built with MCP SDK 1.6.1, Zod validation, tool annotations

## Quick Start

```bash
# Install dependencies
npm install

# Build
npm run build

# Run (stdio mode)
OBSIDIAN_VAULT_PATH=/path/to/vault npm start

# Run (HTTP mode)
OBSIDIAN_VAULT_PATH=/path/to/vault npm run start:http
```

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `OBSIDIAN_VAULT_PATH` | Yes | - | Absolute path to your Obsidian vault |
| `TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
| `PORT` | No | `3000` | HTTP server port |
| `HOST` | No | `127.0.0.1` | HTTP server host |
| `DEBUG` | No | `false` | Enable debug logging |

### MCP Client Configuration

#### Claude Desktop / Cursor / Windsurf (stdio)

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}
```

#### HTTP Mode

Start the server:

```bash
OBSIDIAN_VAULT_PATH=/path/to/vault TRANSPORT=http npm start
```

Connect via `http://localhost:3000/mcp`

## Available Tools

### Note Operations

| Tool | Description |
|------|-------------|
| `obsidian_list_notes` | List notes with pagination and folder filtering |
| `obsidian_read_note` | Read a note's full content and metadata |
| `obsidian_write_note` | Create or update a note |
| `obsidian_delete_note` | Permanently delete a note |
| `obsidian_search_notes` | Search notes by content, tags, or folder |

### Vault Information

| Tool | Description |
|------|-------------|
| `obsidian_vault_stats` | Get vault statistics (note count, size, etc.) |
| `obsidian_list_tags` | List all tags with usage counts |
| `obsidian_get_tagged_notes` | Get all notes with a specific tag |

### Link Navigation

| Tool | Description |
|------|-------------|
| `obsidian_get_links` | Get outgoing links from a note |
| `obsidian_get_backlinks` | Get backlinks to a note |

## Response Formats

All tools support a `response_format` parameter:

- `json` (default): Structured JSON data
- `markdown`: Human-readable markdown

## Development

```bash
# Development mode (with auto-reload)
npm run dev

# Build
npm run build

# Test (builds and runs --help)
npm test
```

## Project Structure

```
src/
  index.ts      # Entry point, transport handling
  server.ts     # MCP server with tool registrations
  vault.ts      # Vault operations (CRUD, search, links)
  schemas.ts    # Zod input validation schemas
  types.ts      # TypeScript type definitions
```

## License

MIT