Provides tools for managing an Obsidian vault, including creating and editing notes, searching content, managing daily notes, creating TODOs with priorities and due dates, discovering backlinks, and saving coding session reports with metadata.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Obsidian MCP Server create a daily note for today with my meeting notes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server for integrating AI assistants with your Obsidian vault. Supports both stdio and HTTP/SSE transports for maximum compatibility.
Session Reports: Automatically save coding session summaries with metadata
Note Management: Create, read, append, and search notes
Daily Notes Integration: Append to daily notes automatically
TODO Tracking: Create and manage TODOs with priorities and due dates
Backlink Discovery: Find notes that link to a specific note
Smart Linking: Get suggestions for related notes based on keywords
Dual Transport: Supports both stdio (direct) and HTTP/SSE (networked) modes
Related MCP server: Obsidian MCP Server
The easiest way to run the server is with Docker Compose:
# Clone the repository
git clone https://github.com/igorilic/obsidian-mcp.git
cd obsidian-mcp
# Create your environment file
cp .env.example .env
# Edit .env and set your vault path
# OBSIDIAN_VAULT_HOST_PATH=/path/to/your/obsidian/vault
# Start the server
docker compose up -d
# Verify it's running
curl http://localhost:9111/healthThe server will be available at http://localhost:9111/mcp.
Node.js 18+
npm or pnpm
git clone https://github.com/igorilic/obsidian-mcp.git
cd obsidian-mcp
npm install
npm run buildClaude Code supports HTTP transport natively. Add to your global config at ~/.claude.json:
{
"mcpServers": {
"obsidian": {
"type": "http",
"url": "http://localhost:9111/mcp"
}
}
}Or for stdio transport (direct, no Docker):
{
"mcpServers": {
"obsidian": {
"type": "stdio",
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}After adding, restart Claude Code or run /mcp to reconnect.
Claude Desktop only supports stdio transport, so use mcp-remote as a bridge for HTTP servers.
Config location:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
For HTTP transport (with Docker):
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:9111/mcp"]
}
}
}For stdio transport (direct, no Docker):
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}Restart Claude Desktop after changes.
Cursor supports MCP servers with stdio, SSE, and HTTP transports.
Config location:
Global: ~/.cursor/mcp.json
Project: .cursor/mcp.json
For stdio transport:
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}For HTTP transport:
{
"mcpServers": {
"obsidian": {
"url": "http://localhost:9111/mcp",
"transport": "sse"
}
}
}Or configure via UI: File → Preferences → Cursor Settings → MCP
Documentation: Cursor MCP Docs
Windsurf uses the same config format as Claude Desktop.
Config location: ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}Or configure via UI: Windsurf Settings → Cascade → Plugins
Documentation: Windsurf MCP Docs
Zed has built-in MCP support but currently only supports stdio transport (not HTTP).
Config location: ~/.config/zed/settings.json
{
"context_servers": {
"obsidian": {
"command": {
"path": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
}To verify: Check the Agent Panel settings - a green indicator means the server is active.
Documentation: Zed MCP Docs
Continue supports MCP servers via YAML configuration files.
Config location: Create .continue/mcpServers/obsidian.yaml in your workspace or home directory:
For stdio transport:
name: Obsidian MCP Server
version: 1.0.0
schema: v1
mcpServers:
- name: obsidian
command: node
args:
- /path/to/obsidian-mcp/dist/index.js
env:
OBSIDIAN_VAULT_PATH: /path/to/your/obsidian/vaultFor HTTP transport:
name: Obsidian MCP Server
version: 1.0.0
schema: v1
mcpServers:
- name: obsidian
type: streamable-http
url: http://localhost:9111/mcpDocumentation: Continue MCP Docs
Cline supports both stdio and SSE transports.
Click the MCP Servers icon in Cline's top navigation → Configure → Advanced MCP Settings
For stdio transport:
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}For SSE/HTTP transport:
{
"mcpServers": {
"obsidian": {
"url": "http://localhost:9111/mcp",
"transport": "sse"
}
}
}Documentation: Cline MCP Docs
JetBrains AI Assistant supports MCP servers starting from version 2025.1.
Setup via UI:
Go to Settings → Tools → AI Assistant → Model Context Protocol (MCP)
Click + to add a new server
Configure the server
For stdio transport:
{
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
}
}Note: MCP tools only work with "Codebase" mode enabled in the chat window.
Documentation: JetBrains MCP Docs
For any client supporting HTTP/SSE MCP transport:
Endpoint: http://localhost:9111/mcp
Health check: http://localhost:9111/health
Protocol: MCP over Streamable HTTP (SSE responses)
Required headers: Accept: application/json, text/event-stream
Example initialization request:
curl -X POST http://localhost:9111/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {"name": "my-client", "version": "1.0.0"}
}
}'Best for:
Multiple clients connecting simultaneously
Networked/remote access
Containerized deployments
# Using Docker
docker compose up -d
# Or manually
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 node dist/index.jsBest for:
Direct integration with IDEs
Single client usage
Lower latency
OBSIDIAN_VAULT_PATH=/path/to/vault node dist/index.jsTool | Description |
| Save coding session summaries with metadata |
| Create or overwrite a note |
| Append content to an existing note |
| Append to today's daily note |
| Search notes by content, tags, or folder |
| Read a note's content and frontmatter |
| List recently modified notes |
| Find notes linking to a specific note |
| Create a TODO item |
| Get suggestions for related notes |
{
title: string; // Short title (required)
summary: string; // Brief summary (required)
details?: string; // Detailed description
files_changed?: string[]; // List of modified files
next_steps?: string[]; // Follow-up TODOs
tags?: string[]; // Tags for categorization
project?: string; // Project name
folder?: string; // Subfolder in Claude-Sessions
}{
path: string; // Relative path (required)
content: string; // Markdown content (required)
title?: string; // Note title
tags?: string[]; // Tags
frontmatter?: object; // Additional frontmatter
}{
query: string; // Search query (required)
tags?: string[]; // Filter by tags
folder?: string; // Limit to folder
limit?: number; // Max results (default: 20)
}{
task: string; // Task description (required)
project?: string; // Project tag
priority?: string; // "high" | "medium" | "low"
due_date?: string; // YYYY-MM-DD format
context?: string; // Additional context
todo_file?: string; // Target file (default: "TODOs.md")
}Variable | Description | Default |
| Path to Obsidian vault | Required |
| Transport mode: |
|
| HTTP server port (when using http transport) |
|
The server creates/uses this structure:
Your Vault/
├── Claude-Sessions/ # Session reports
│ ├── project-name/ # Per-project folders
│ │ └── 2024-01-15-1430-feature-complete.md
│ └── 2024-01-15-1200-quick-fix.md
├── Daily Notes/ # Daily notes (configurable)
│ └── 2024-01-15.md
└── TODOs.md # TODO items# Watch mode
npm run dev
# Build
npm run build
# Run with stdio
OBSIDIAN_VAULT_PATH=/path/to/vault npm start
# Run with HTTP
MCP_TRANSPORT=http npm start
# Docker build
docker compose build
# Docker logs
docker compose logs -fThe MCP client has a stale session. Solutions:
Claude Code: Run /mcp to reconnect
Claude Desktop: Restart the app
Docker: Run docker compose restart
Ensure the server is running:
curl http://localhost:9111/healthIf using Docker, ensure the vault is mounted with write access (:rw not :ro) in your .env file.
Check server logs: docker compose logs
Verify configuration path is correct
Restart your IDE/client
For JetBrains: Ensure "Codebase" mode is enabled
Zed doesn't support HTTP transport yet. Use stdio configuration instead.
MIT
Append content to today's daily note. Creates the daily note if it doesn't exist.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Content to append to daily note | |
| section | No | Section header to append under (e.g., '## Claude Sessions') | |
| daily_folder | No | Folder for daily notes (default: 'Daily Notes') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the core behavior (appending with conditional creation) but lacks details about permissions, file format, error handling, or whether appending adds newlines. It's adequate but has clear gaps for a mutation tool without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just two sentences that are front-loaded and waste no words. Every phrase ('Append content to today's daily note', 'Creates the daily note if it doesn't exist') directly contributes to understanding the tool's purpose and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers the basic operation adequately but lacks important contextual details. It doesn't explain what the tool returns (e.g., success confirmation, note content), error conditions, or how it interacts with the note-taking system's conventions, leaving gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, such as examples for 'section' beyond what the schema provides. This meets the baseline of 3 when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Append content') and resource ('today's daily note'), including the conditional creation behavior. It distinguishes from sibling tools like 'append_to_note' by specifying 'daily note' and 'today's', and from 'write_note' by focusing on appending rather than overwriting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: for appending to today's daily note, with automatic creation if missing. However, it doesn't explicitly state when not to use it or name alternatives like 'append_to_note' for non-daily notes or 'write_note' for overwriting, which would be needed for a score of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append content to an existing note. Useful for adding entries to running logs, daily notes, or accumulating information.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the note | |
| content | Yes | Content to append | |
| add_timestamp | No | Whether to add a timestamp header (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Append content to an existing note' implies mutation (not read-only), it doesn't specify permissions needed, whether the operation is atomic, what happens if the note doesn't exist, or any rate limits. The description mentions use cases but lacks critical behavioral details for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place. The first sentence states the core functionality, and the second provides valuable usage context. No wasted words, and the most important information (what the tool does) comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description provides adequate basic information about purpose and usage context. However, it lacks important details about error conditions, return values, and behavioral constraints that would be needed for complete understanding. The description does its job reasonably well given the tool's moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Append content') and target resource ('to an existing note'), making the purpose immediately understandable. It distinguishes from sibling tools like 'write_note' (which likely creates/overwrites) and 'read_note' (which only reads). However, it doesn't explicitly contrast with 'append_to_daily_note' which appears to be a more specific variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('Useful for adding entries to running logs, daily notes, or accumulating information'), giving practical scenarios. It implicitly suggests this is for incremental updates rather than full replacements. However, it doesn't explicitly state when NOT to use it or name specific alternatives like 'write_note' for overwriting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or add a TODO item. Can create a new TODO note or append to existing TODO list.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | The TODO task description | |
| project | No | Project name for organization | |
| priority | No | Task priority | |
| due_date | No | Due date (YYYY-MM-DD format) | |
| context | No | Additional context about the task | |
| todo_file | No | Path to TODO file (default: 'TODOs.md') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers limited behavioral insight. It mentions the tool can 'create or add' and 'append to existing TODO list', but doesn't disclose permissions needed, whether it overwrites or merges content, error handling, or file system implications. For a mutation tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two clear sentences that efficiently convey the core functionality. However, the second sentence slightly repeats the first ('create' vs 'create or add'), and it could be more front-loaded with critical distinctions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 6 parameters, no annotations, and no output schema, the description is incomplete. It lacks essential context like required permissions, file path defaults/behavior, error scenarios, and what 'append' means operationally. The agent would struggle to use this tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds no parameter-specific information beyond the generic 'create or add' context, which doesn't enhance understanding of individual parameters. Baseline 3 is appropriate when the schema does all the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('create or add') and resource ('TODO item'), specifying it can create new items or append to existing lists. However, it doesn't distinguish this tool from sibling tools like 'append_to_note' or 'write_note' which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance by mentioning 'create or add' and 'append to existing TODO list', but offers no explicit when-to-use rules, prerequisites, or comparisons to alternatives like 'append_to_daily_note' or 'write_note'. This leaves the agent with unclear decision boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all notes that link to a specific note.
| Name | Required | Description | Default |
|---|---|---|---|
| note_name | Yes | Name of the note (without .md extension) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but doesn't describe how it behaves—e.g., whether it returns a list, paginates results, requires specific permissions, or has rate limits. For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is front-loaded with the core purpose and efficiently communicates the tool's function. Every part of the description earns its place by directly stating what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., a list of note names or full content), behavioral traits like error handling, or how it integrates with sibling tools. For a tool with no structured metadata, the description should provide more context to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with 'note_name' clearly documented as 'Name of the note (without .md extension).' The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints. Given the high schema coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find all notes that link to a specific note.' It specifies the verb ('find') and resource ('notes that link to a specific note'), making it easy to understand. However, it doesn't explicitly differentiate from siblings like 'search_notes' or 'link_notes', which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios where this tool is preferred over 'search_notes' or 'link_notes', nor does it specify prerequisites or exclusions. This lack of context leaves the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get suggestions for notes that might be related to given content or keywords.
| Name | Required | Description | Default |
|---|---|---|---|
| keywords | Yes | Keywords to find related notes for | |
| content | No | Content to analyze for potential links | |
| limit | No | Maximum number of suggestions (default: 10) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'Get suggestions' but doesn't clarify whether this is a read-only operation, how suggestions are generated (e.g., semantic similarity, keyword matching), what the output format is, or any performance considerations. For a tool with 3 parameters and no annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the core purpose without unnecessary words. It is front-loaded with the main action and resource, making it easy to parse. Every part of the sentence earns its place by specifying inputs ('content or keywords') and output ('suggestions for notes').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no annotations, no output schema), the description is incomplete. It lacks details on behavioral traits (e.g., how suggestions are generated, output format), usage guidelines relative to siblings, and parameter interactions. Without annotations or an output schema, the description should provide more context to fully inform the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with clear descriptions for all parameters. The description adds no additional parameter semantics beyond what the schema provides—it mentions 'keywords' and 'content' but doesn't explain their interplay or prioritization. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, though the description doesn't compensate for any gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get suggestions for notes that might be related to given content or keywords.' It specifies the action ('Get suggestions') and resource ('notes'), distinguishing it from siblings like 'search_notes' (which likely returns exact matches) or 'find_backlinks' (which finds explicit references). However, it doesn't explicitly differentiate from 'search_notes' beyond implying a 'relatedness' focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to prefer 'link_notes' over 'search_notes' or 'find_backlinks', nor does it specify prerequisites or exclusions. The agent must infer usage from the purpose alone, which is insufficient for optimal tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recently modified notes in the vault.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of notes to return (default: 20) | |
| folder | No | Limit to a specific folder |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool lists notes but lacks details on permissions, rate limits, pagination, or what 'recently modified' means (e.g., time frame, sorting). This is a significant gap for a tool with no structured safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, no output schema, no annotations), the description is minimally adequate but incomplete. It covers the basic purpose but lacks behavioral details and usage guidelines, which are needed for the agent to operate effectively in a context with multiple note-related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, clearly documenting both parameters ('limit' and 'folder') with their types and defaults. The description doesn't add any additional meaning beyond this, such as explaining how 'folder' paths work or constraints on 'limit', so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('List') and resource ('recently modified notes in the vault'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'search_notes' or 'find_backlinks', which might also retrieve notes, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios like retrieving recent changes versus searching by content, nor does it reference sibling tools such as 'search_notes' or 'read_note' for comparison, leaving the agent without clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the content of a specific note.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the note |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. While 'Read' implies a read-only operation, it doesn't specify permissions needed, error handling (e.g., if the note doesn't exist), or what the output contains (e.g., raw text, metadata). This leaves significant gaps for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's front-loaded with the core purpose, making it easy for an agent to parse quickly. Every word earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete for a read operation. It doesn't explain what is returned (e.g., note content, formatting, metadata) or address potential errors, leaving the agent with insufficient context to use the tool effectively beyond the basic parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'path' documented as 'Relative path to the note'. The description adds no additional meaning beyond this, such as path format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and resource ('content of a specific note'), making the purpose immediately understandable. However, it doesn't differentiate this tool from potential siblings like 'list_recent_notes' or 'search_notes' that might also involve reading notes, missing an opportunity for clearer distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'list_recent_notes' and 'search_notes' available, there's no indication whether this is for reading a single known note versus browsing or searching, leaving the agent to guess based on context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search notes in the vault by content, tags, or folder.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (searches in content and titles) | |
| tags | No | Filter by tags | |
| folder | No | Limit search to a specific folder | |
| limit | No | Maximum number of results (default: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions searching but doesn't disclose behavioral traits such as whether results are paginated, if the search is case-sensitive, what the return format is, or any rate limits. This is a significant gap for a search tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('Search notes in the vault') and specifies searchable attributes. There is zero waste, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a search tool with 4 parameters, no annotations, and no output schema, the description is incomplete. It lacks details on behavioral aspects (e.g., result format, pagination) and doesn't compensate for the absence of structured fields, making it inadequate for full agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters (query, tags, folder, limit) with descriptions. The description adds no additional meaning beyond what's in the schema, such as search syntax or interaction between parameters. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('search') and resource ('notes in the vault'), specifying the searchable attributes ('by content, tags, or folder'). It distinguishes from siblings like 'list_recent_notes' (which lacks search) and 'find_backlinks' (which focuses on links), though it doesn't explicitly name these distinctions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching notes based on content, tags, or folders, but doesn't explicitly state when to use this vs. alternatives like 'list_recent_notes' (for recent notes without search) or 'find_backlinks' (for link-based queries). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write or create a note in the Obsidian vault. Can be used for documentation, meeting notes, ideas, or any other content.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path in vault (e.g., 'Projects/my-project/notes.md') | |
| title | No | Note title (used in frontmatter) | |
| content | Yes | Markdown content of the note | |
| tags | No | Tags for the note | |
| frontmatter | No | Additional frontmatter fields |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'Write or create a note,' implying a write operation, but doesn't disclose critical behavioral traits such as whether it overwrites existing notes, requires specific permissions, handles errors, or has rate limits. The description adds minimal context beyond the basic action, leaving significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, stating the core purpose in the first sentence. The second sentence adds useful context without redundancy. Both sentences earn their place by clarifying the tool's function and providing examples, though it could be slightly more structured by explicitly mentioning key parameters or behavioral aspects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, including nested objects, no output schema, and no annotations), the description is incomplete. It doesn't address behavioral traits like overwrite behavior, error handling, or output format, and lacks usage guidelines compared to siblings. For a write operation with multiple parameters and no structured safety hints, more comprehensive context is needed to adequately inform an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all parameters are documented in the input schema. The description adds no specific parameter semantics beyond implying general note creation. It doesn't explain interactions between parameters (e.g., how 'title' relates to 'path' or 'frontmatter'), so it provides no extra value over the schema. Baseline 3 is appropriate when the schema handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Write or create a note in the Obsidian vault.' It specifies the action (write/create) and resource (note in Obsidian vault), and provides examples of use cases (documentation, meeting notes, ideas). However, it doesn't explicitly differentiate from sibling tools like 'append_to_note' or 'write_session_report', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions general use cases ('documentation, meeting notes, ideas, or any other content'), but provides no explicit guidance on when to use this tool versus alternatives. For example, it doesn't clarify when to choose 'write_note' over 'append_to_note' or 'write_session_report', nor does it mention prerequisites or exclusions. This lack of comparative context results in minimal guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a session report to the Obsidian vault. Use this at the end of coding sessions, after completing significant tasks, or when wrapping up work phases. The report will be saved with proper frontmatter and timestamps.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Short title for the session (e.g., 'Refactored auth module') | |
| summary | Yes | Brief summary of what was accomplished | |
| details | No | Detailed description of changes, decisions, and context | |
| files_changed | No | List of files that were modified | |
| next_steps | No | List of follow-up tasks or TODOs | |
| tags | No | Tags for categorization (e.g., ['refactoring', 'auth', 'security']) | |
| project | No | Project name for organization | |
| folder | No | Subfolder within Claude-Sessions (default: uses project name or root) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the report will be saved 'with proper frontmatter and timestamps,' which adds some context beyond basic writing. However, it doesn't cover important behavioral aspects like whether this overwrites existing files, requires specific permissions, handles errors, or provides confirmation of success—critical for a write operation with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise and well-structured: two sentences that efficiently convey purpose and usage guidelines. Every word earns its place with no redundancy or fluff. It's front-loaded with the core action and follows with specific context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, write operation) and lack of annotations/output schema, the description is minimally adequate. It covers purpose and usage context well but lacks behavioral details about the write operation's effects, error handling, or confirmation. For a tool that creates persistent artifacts, more disclosure about what 'saved' means would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 8 parameters. The description doesn't add any parameter-specific information beyond what's in the schema (e.g., it doesn't explain parameter relationships or provide examples). With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Write a session report to the Obsidian vault' with specific context about when to use it (end of coding sessions, after significant tasks, wrapping up work phases). It distinguishes from siblings like 'write_note' by specifying session reports with frontmatter and timestamps, though not explicitly contrasting with all siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Use this at the end of coding sessions, after completing significant tasks, or when wrapping up work phases.' This gives explicit guidance on when to invoke the tool. However, it doesn't specify when NOT to use it or mention alternatives among sibling tools like 'append_to_daily_note' or 'write_note'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0append_to_daily_noteappend_to_notecreate_todofind_backlinkslink_noteslist_recent_notesread_notesearch_noteswrite_notewrite_session_reportScored across 10 tools
Most tools have distinct purposes, but there is some overlap between 'append_to_daily_note' and 'append_to_note' that could cause confusion, as both handle appending content. Additionally, 'create_todo' and 'write_note' might be ambiguous for creating new notes, though their specific focuses help differentiate them.
The naming follows a consistent verb_noun pattern throughout, such as 'append_to_daily_note', 'read_note', and 'search_notes'. Minor deviations like 'find_backlinks' (which could be 'list_backlinks') and 'link_notes' (which suggests linking but is for suggestions) slightly break the pattern, but overall it's highly readable and predictable.
With 10 tools, this server is well-scoped for managing an Obsidian vault, covering key operations like reading, writing, appending, searching, and listing notes. Each tool serves a clear purpose, and the count aligns well with typical MCP server ranges, avoiding bloat or thinness.
The toolset provides strong coverage for core Obsidian workflows, including CRUD operations (create, read, write, append) and utilities like search and backlinks. Minor gaps exist, such as the lack of update or delete operations for notes, which might require workarounds, but agents can handle most tasks effectively with the available tools.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
