npm package: @manex/obsidianmcp
Description: A Model Context Protocol server for secure integration with Obsidian vaults
Author: Manex142
Latest version: 0.1.4

# ObsidianMCP

A lightweight, secure Model Context Protocol (MCP) server for seamless Obsidian vault integration with AI assistants and automation tools.

Interact with your Obsidian vault through MCP-compatible clients like **Claude Desktop**, **VSCode**, or any other MCP-enabled application.

## Features

- **List notes** - Browse your entire vault structure with folder hierarchy
- **Read notes** - Access note content securely
- **Create notes** - Add new notes with initial content
- **Append content** - Extend existing notes
- **Delete notes** - Remove notes safely
- **Search** - Find notes by name or content
- **Health checks** - Monitor server status and vault accessibility

Perfect for integrating Obsidian with AI agents, building automations, and creating advanced workflows.

## Available Tools

| Tool             | Description                                    | Parameters                                                                                |
| ---------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `check_health`   | Check server health and vault accessibility.   | —                                                                                         |
| `list_notes`     | List all markdown notes with folder hierarchy. | —                                                                                         |
| `read_note`      | Read the content of a specific note.           | `note`: Note path (e.g., `Personal/Diary.md`)                                             |
| `create_note`    | Create a new note. Fails if it already exists. | `note`: Note path<br>`content`: Initial content (optional)                                |
| `append_to_note` | Append content to an existing note.            | `note`: Note path<br>`content`: Text to append                                            |
| `delete_note`    | Delete a note. This action is irreversible.    | `note`: Note path                                                                         |
| `search_notes`   | Search notes by name or content.               | `query`: Search text<br>`searchContent`: Also search content (optional, default: `false`) |

## Quick Start

Just add this to your MCP client configuration:

### Claude Code

Edit `~/.claude.json`:

```json
{
  "mcpServers": {
    "obsidian": {
      "type": "stdio",
      "command": "npx",
      "args": ["@manex/obsidianmcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "~/Documents/ObsidianVault"
      }
    }
  }
}
```

### VSCode (Copilot)

Edit `~/.config/Code/User/mcp.json`:

```jsonc
{
  "servers": {
    "obsidian": {
      "type": "stdio",
      "command": "npx",
      "args": ["@manex/obsidianmcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "~/Documents/ObsidianVault",
      },
    },
  },
}
```

Replace `~/Documents/ObsidianVault` with your actual Obsidian vault path. You can use `~` for the home directory.

> **Note:** `OBSIDIAN_VAULT_PATH` must point to an existing Obsidian vault directory.

## Development

### Requirements

- **Node.js** v18+ (or **Bun** v1.0+ for development build)
- **Obsidian** vault (local directory)

### Available Scripts

| Command             | Description                     |
| ------------------- | ------------------------------- |
| `bun run dev`       | Run server in development mode  |
| `bun run build`     | Build for production            |
| `bun run start`     | Run the compiled server         |
| `bun test`          | Run test suite                  |
| `bun test --watch`  | Run tests in watch mode         |
| `bun run typecheck` | Type check with TypeScript      |
| `bun run inspector` | Run MCP inspector for debugging |

## Project Structure

```
src/
├── server.ts          # MCP server entry point
├── config/            # Configuration & environment validation
├── errors/            # Typed error classes
├── schemas/           # Zod input validation schemas
├── tools/             # MCP tool implementations
├── types/             # TypeScript type definitions
└── utils/             # File system & security utilities
```

## Security

Built with security as a first-class concern:

- **Path traversal prevention** - Validates all paths against vault boundaries
- **Symlink escape detection** - Prevents breaking out via symbolic links
- **DoS protection** - Limits recursion depth and result counts
- **TOCTOU prevention** - Atomic file operations for safe concurrent access
- **Input validation** - All inputs validated with Zod schemas

## License

MIT

## Support

Found a bug or have a feature request? Open an [issue](https://github.com/Manex142/ObsidianMCP/issues).

---

**Built with** [Bun](https://bun.sh) and [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)