obsidian-mcp/specs/001-obsidian-mcp-bundle/contracts/tools.md

Tool Schemas

Purpose: Define input/output schemas for all MCP tools exposed by the Obsidian bundle

Tool Naming Convention

All tools use prefix obsidian_ followed by the operation:

• obsidian_create_note
• obsidian_search
• obsidian_list_tasks

This prevents naming conflicts with other MCP servers.

Priority 1 Tools: File Operations (15 tools)

obsidian_create_note

Description: Create a new note in the vault

Input Schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Note name (without .md extension) or exact path",
      "minLength": 1,
      "maxLength": 255
    },
    "path": {
      "type": "string",
      "description": "Optional: Directory path within vault"
    },
    "content": {
      "type": "string",
      "description": "Initial note content (markdown)"
    },
    "template": {
      "type": "string",
      "description": "Template name to use"
    },
    "overwrite": {
      "type": "boolean",
      "description": "Overwrite if file exists (default: false)"
    },
    "open": {
      "type": "boolean",
      "description": "Open file after creating (default: false)"
    }
  },
  "required": ["name"]
}

Output Example:

{
  "success": true,
  "data": {
    "path": "Projects/Meeting Notes.md",
    "created": true,
    "opened": false
  }
}

---

obsidian_read_note

Description: Read the contents of a note

Input Schema:

{
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "description": "Note name (wikilink-style resolution)"
    },
    "path": {
      "type": "string",
      "description": "Exact path to note"
    }
  },
  "oneOf": [{"required": ["file"]}, {"required": ["path"]}]
}

Output Example:

{
  "success": true,
  "data": {
    "path": "Projects/Meeting Notes.md",
    "content": "# Meeting Notes\n\n- Agenda item 1\n- Agenda item 2",
    "size": 52,
    "modified": "2026-03-22T15:30:00Z"
  }
}

---

obsidian_append_to_note

Description: Append content to a note

Input Schema:

{
  "type": "object",
  "properties": {
    "file": {"type": "string"},
    "path": {"type": "string"},
    "content": {
      "type": "string",
      "description": "Content to append (required)"
    },
    "inline": {
      "type": "boolean",
      "description": "Append without newline (default: false)"
    }
  },
  "required": ["content"],
  "oneOf": [{"required": ["file"]}, {"required": ["path"]}]
}

---

obsidian_delete_note

Description: Delete a note (moves to trash by default)

Input Schema:

{
  "type": "object",
  "properties": {
    "file": {"type": "string"},
    "path": {"type": "string"},
    "permanent": {
      "type": "boolean",
      "description": "Skip trash, delete permanently (default: false)"
    }
  },
  "oneOf": [{"required": ["file"]}, {"required": ["path"]}]
}

---

obsidian_move_note

Description: Move or rename a note

Input Schema:

{
  "type": "object",
  "properties": {
    "file": {"type": "string"},
    "path": {"type": "string"},
    "to": {
      "type": "string",
      "description": "Destination folder or full path (required)"
    }
  },
  "required": ["to"],
  "oneOf": [{"required": ["file"]}, {"required": ["path"]}]
}

---

Priority 2 Tools: Search & Discovery (20 tools)

obsidian_search

Description: Search vault for text

Input Schema:

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query (required)"
    },
    "folder": {
      "type": "string",
      "description": "Limit search to specific folder"
    },
    "limit": {
      "type": "number",
      "description": "Maximum number of results"
    },
    "caseSensitive": {
      "type": "boolean",
      "description": "Case-sensitive search (default: false)"
    }
  },
  "required": ["query"]
}

Output Example:

{
  "success": true,
  "data": {
    "query": "machine learning",
    "matchCount": 5,
    "files": [
      {"path": "Research/AI Notes.md", "matches": 3},
      {"path": "Projects/ML Project.md", "matches": 2}
    ]
  }
}

---

obsidian_get_backlinks

Description: List backlinks to a note

Input Schema:

{
  "type": "object",
  "properties": {
    "file": {"type": "string"},
    "path": {"type": "string"},
    "counts": {
      "type": "boolean",
      "description": "Include link counts (default: false)"
    }
  },
  "oneOf": [{"required": ["file"]}, {"required": ["path"]}]
}

Output Example:

{
  "success": true,
  "data": {
    "target": "Projects/ML Project.md",
    "backlinks": [
      {"source": "Research/AI Notes.md", "count": 2},
      {"source": "Weekly Review.md", "count": 1}
    ],
    "totalBacklinks": 2
  }
}

---

obsidian_list_tags

Description: List tags in the vault or specific file

Input Schema:

{
  "type": "object",
  "properties": {
    "file": {"type": "string", "description": "Limit to specific file"},
    "path": {"type": "string", "description": "Limit to specific path"},
    "counts": {
      "type": "boolean",
      "description": "Include occurrence counts (default: false)"
    },
    "sortBy": {
      "type": "string",
      "enum": ["name", "count"],
      "description": "Sort order (default: name)"
    }
  }
}

Output Example:

{
  "success": true,
  "data": {
    "tags": [
      {"name": "project", "count": 15},
      {"name": "important", "count": 8},
      {"name": "todo", "count": 5}
    ],
    "totalTags": 3
  }
}

---

Priority 3 Tools: Tasks & Properties (15 tools)

obsidian_list_tasks

Description: List tasks in the vault or specific file

Input Schema:

{
  "type": "object",
  "properties": {
    "file": {"type": "string"},
    "path": {"type": "string"},
    "status": {
      "type": "string",
      "enum": ["todo", "done", "all"],
      "description": "Filter by status (default: all)"
    },
    "verbose": {
      "type": "boolean",
      "description": "Group by file with line numbers (default: false)"
    }
  }
}

Output Example:

{
  "success": true,
  "data": {
    "tasks": [
      {
        "ref": "Projects/TODO.md:5",
        "file": "Projects/TODO.md",
        "line": 5,
        "text": "Finish documentation",
        "status": "",
        "done": false
      },
      {
        "ref": "Weekly Review.md:12",
        "file": "Weekly Review.md",
        "line": 12,
        "text": "Review PRs",
        "status": "x",
        "done": true
      }
    ],
    "totalTasks": 2
  }
}

---

obsidian_toggle_task

Description: Toggle a task's completion status

Input Schema:

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "description": "Task reference (path:line)"
    },
    "file": {"type": "string"},
    "path": {"type": "string"},
    "line": {
      "type": "number",
      "description": "Line number (1-indexed)"
    }
  },
  "oneOf": [
    {"required": ["ref"]},
    {"required": ["file", "line"]},
    {"required": ["path", "line"]}
  ]
}

---

obsidian_set_property

Description: Set a property value on a note

Input Schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Property name (required)"
    },
    "value": {
      "description": "Property value (required, type: string|number|boolean|array)"
    },
    "type": {
      "type": "string",
      "enum": ["text", "number", "checkbox", "date", "datetime", "list"],
      "description": "Property type (optional, inferred from value)"
    },
    "file": {"type": "string"},
    "path": {"type": "string"}
  },
  "required": ["name", "value"],
  "oneOf": [{"required": ["file"]}, {"required": ["path"]}]
}

---

Priority 4 Tools: Vault Navigation (15 tools)

obsidian_list_files

Description: List files in the vault

Input Schema:

{
  "type": "object",
  "properties": {
    "folder": {
      "type": "string",
      "description": "Filter by folder"
    },
    "extension": {
      "type": "string",
      "description": "Filter by extension (e.g., 'md')"
    }
  }
}

---

obsidian_get_vault_info

Description: Get vault statistics

Input Schema:

{
  "type": "object",
  "properties": {
    "info": {
      "type": "string",
      "enum": ["name", "path", "files", "folders", "size", "all"],
      "description": "Specific info to return (default: all)"
    }
  }
}

Output Example:

{
  "success": true,
  "data": {
    "name": "My Vault",
    "path": "/Users/user/Documents/Obsidian/My Vault",
    "fileCount": 1234,
    "folderCount": 56,
    "totalSize": 5242880
  }
}

---

Priority 5 Tools: Advanced Features (30 tools)

obsidian_daily_append

Description: Append content to today's daily note

Input Schema:

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Content to append (required)"
    },
    "inline": {
      "type": "boolean",
      "description": "Append without newline (default: false)"
    },
    "open": {
      "type": "boolean",
      "description": "Open daily note after appending (default: false)"
    }
  },
  "required": ["content"]
}

---

obsidian_list_templates

Description: List available templates

Input Schema:

{
  "type": "object",
  "properties": {}
}

---

obsidian_list_plugins

Description: List installed plugins

Input Schema:

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "string",
      "enum": ["core", "community", "all"],
      "description": "Filter by plugin type (default: all)"
    },
    "enabledOnly": {
      "type": "boolean",
      "description": "Show only enabled plugins (default: false)"
    },
    "includeVersions": {
      "type": "boolean",
      "description": "Include version numbers (default: false)"
    }
  }
}

---

Complete Tool List (95 tools)

File Operations (15)

1. obsidian_create_note
2. obsidian_read_note
3. obsidian_append_to_note
4. obsidian_prepend_to_note
5. obsidian_delete_note
6. obsidian_move_note
7. obsidian_rename_note
8. obsidian_open_note
9. obsidian_get_file_info
10. obsidian_list_recents
11. obsidian_get_outline
12. obsidian_get_wordcount
13. obsidian_random_note
14. obsidian_open_file
15. obsidian_list_orphans

Search & Discovery (20)

16. obsidian_search
17. obsidian_search_with_context
18. obsidian_get_backlinks
19. obsidian_get_outgoing_links
20. obsidian_list_unresolved_links
21. obsidian_list_tags
22. obsidian_get_tag_info
23. obsidian_list_aliases
24. obsidian_list_properties
25. obsidian_get_property_count
26. obsidian_list_deadends
27. obsidian_list_files
28. obsidian_list_folders
29. obsidian_get_folder_info
30. obsidian_get_vault_info
31. obsidian_list_vaults
32. obsidian_open_search
33. obsidian_get_version
34. obsidian_reload_vault
35. obsidian_list_workspace_tabs

Tasks & Properties (15)

36. obsidian_list_tasks
37. obsidian_toggle_task
38. obsidian_mark_task_done
39. obsidian_mark_task_todo
40. obsidian_update_task_status
41. obsidian_get_property
42. obsidian_set_property
43. obsidian_remove_property
44. obsidian_list_note_properties
45. obsidian_list_vault_properties
46. obsidian_daily_tasks
47. obsidian_active_file_tasks
48. obsidian_active_file_properties
49. obsidian_active_file_tags
50. obsidian_active_file_aliases

Daily Notes (6)

51. obsidian_open_daily_note
52. obsidian_daily_append
53. obsidian_daily_prepend
54. obsidian_daily_read
55. obsidian_daily_path
56. obsidian_random_read

Templates & Bookmarks (8)

57. obsidian_list_templates
58. obsidian_read_template
59. obsidian_insert_template
60. obsidian_create_bookmark
61. obsidian_list_bookmarks
62. obsidian_bookmark_file
63. obsidian_bookmark_search
64. obsidian_bookmark_url

Plugins & Themes (12)

65. obsidian_list_plugins
66. obsidian_list_enabled_plugins
67. obsidian_get_plugin_info
68. obsidian_enable_plugin
69. obsidian_disable_plugin
70. obsidian_list_themes
71. obsidian_get_active_theme
72. obsidian_set_theme
73. obsidian_list_css_snippets
74. obsidian_enable_snippet
75. obsidian_disable_snippet
76. obsidian_restricted_mode_status

File History & Sync (12)

77. obsidian_list_file_versions
78. obsidian_read_version
79. obsidian_restore_version
80. obsidian_list_files_with_history
81. obsidian_open_history
82. obsidian_list_sync_versions
83. obsidian_read_sync_version
84. obsidian_restore_sync_version
85. obsidian_get_sync_status
86. obsidian_pause_sync
87. obsidian_resume_sync
88. obsidian_list_sync_deleted

Bases & Commands (7)

89. obsidian_list_bases
90. obsidian_list_base_views
91. obsidian_query_base
92. obsidian_create_base_item
93. obsidian_list_commands
94. obsidian_execute_command
95. obsidian_get_hotkey

Error Response Format

All tools return errors in consistent structure:

{
  "success": false,
  "error": {
    "code": "OBSIDIAN_NOT_RUNNING",
    "message": "Obsidian application is not running. Please start Obsidian and try again.",
    "details": {
      "attempted": "create_note",
      "file": "Meeting Notes.md"
    }
  }
}

Validation Rules

All input schemas enforce:

• String min/max lengths
• Required fields
• Enum constraints for predefined values
• Type coercion where safe
• Sanitization of special characters before CLI execution