Shard

Lightweight, type-safe Model Context Protocol (MCP) server for Obsidian. Shard exposes note, search, template, and property operations to MCP clients through the local Obsidian CLI.

Features

• Read and write Markdown notes, including frontmatter properties.
• Create, delete, search, append, prepend, rename, move, and patch notes.
• Local stdio transport: no HTTP server or network credentials.

Requirements

• Obsidian CLI enabled in Settings → General → Command line interface.
• obsidian-cli available in the current directory or PATH on macOS/Linux, or obsidian.com on Windows.
• Running Obsidian in background.

Installation

Download the archive for your operating system and architecture from the latest GitHub release, then extract it.

Move the shard binary (shard.exe on Windows) to a directory in your PATH, or use its absolute path in the MCP client configuration. On macOS/Linux, make it executable with chmod +x shard.

MCP client configuration

Shard should be supported by any agent that has support for MCP servers. Here's some examples of how to configure Shard for your agent:

Codex

Add this to your config.toml to make Shard available in Codex:

[mcp_servers.obsidian]
enabled = true
command = '/absolute/path/to/shard'
args = ["start"]
default_tools_approval_mode = "approve"

Claude Code

Add Shard for every project of current user:

claude mcp add obsidian --scope user -- /absolute/path/to/shard start
claude mcp list

Use --scope project to create a shareable .mcp.json in current repository instead. Claude Code asks for approval before using project-scoped servers.

Claude Desktop

Open Settings → Developer → Edit Config, then add this entry to claude_desktop_config.json and restart Claude Desktop:

{
  "mcpServers": {
    "obsidian": {
      "command": "/absolute/path/to/shard",
      "args": ["start"]
    }
  }
}

Cursor

Create .cursor/mcp.json for current project, or ~/.cursor/mcp.json for every project. Add this configuration, then restart Cursor or reconnect the server in Settings → Tools & MCP:

{
  "mcpServers": {
    "obsidian": {
      "command": "/absolute/path/to/shard",
      "args": ["start"]
    }
  }
}

VS Code / GitHub Copilot

Create .vscode/mcp.json for current workspace. For a global server, run MCP: Open User Configuration from Command Palette instead. Restart the server through MCP: List Servers after saving.

{
  "servers": {
    "obsidian": {
      "command": "/absolute/path/to/shard",
      "args": ["start"]
    }
  }
}

Pi

Pi has no built-in MCP client. Install an MCP extension once:

pi install npm:pi-mcp-adapter

Create ~/.pi/agent/mcp.json for current user, or .pi/mcp.json for current project. Start Pi, then use /mcp to check server status.

{
  "mcpServers": {
    "obsidian": {
      "command": "/absolute/path/to/shard",
      "args": ["start"],
      "transport": "stdio",
      "lifecycle": "eager"
    }
  }
}

OpenCode

Create opencode.json in current project, or ~/.config/opencode/opencode.json for current user. Then run opencode mcp list.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "obsidian": {
      "type": "local",
      "command": ["/absolute/path/to/shard", "start"],
      "enabled": true
    }
  },
  "permission": {
    "obsidian_*": "ask"
  }
}

Configuration references: Claude Code, Cursor, VS Code, Pi MCP extension, and OpenCode.

Tools

Here's a table of tools that agents has access to:

Tool	Input	Purpose
read_note	path	Read Markdown body and frontmatter properties.
create_note	path, content, properties, overwrite	Create a note or overwrite an existing note.
delete_note	path	Move note to trash.
append_note	path, content, inline	Add content at the end of a note.
prepend_note	path, content, inline	Add content after frontmatter and before the body.
rename_note	path, name	Change a note's filename.
move_note	path, to	Move a note to another vault path.
patch_note	path, old_text, new_text, replace_all	Replace exact text in a note.
search	query, optional limit, total, case	Search note paths or return only match count.
list_templates	none	List configured templates.
read_template	name, optional title, resolve	Read a template and optionally resolve variables.
get_all_properties	none	List property types and occurrence counts.

License

This project is licensed under the MIT License. See LICENSE for details.