Obsidian MCP Server

Instructions

Implementation Reference

• src/obsidian_mcp/server.py:232-279 (handler)

  MCP tool handler for list_notes: validates inputs, calls vault.list_notes, formats results as numbered list with path, size, and tags.
  @mcp.tool(name="list_notes", description="List notes in the vault with optional filters") def list_notes(folder: str = "", recursive: bool = True, limit: int = 100) -> str: """ List notes in the vault. Args: folder: Folder to list (empty for root) recursive: Include subfolders (default: true) limit: Maximum number of results (default: 100) Returns: Formatted list of notes with metadata """ # Validate input if limit <= 0 or limit > 10000: return "Error: Limit must be between 1 and 10000" context = _get_context() try: notes = context.vault.list_notes(folder=folder, recursive=recursive, limit=limit) if not notes: folder_desc = f" in '{folder}'" if folder else "" return f"No notes found{folder_desc}" # Format results folder_desc = f" in '{folder}'" if folder else "" output = f"Found {len(notes)} notes{folder_desc}:\n\n" for i, note in enumerate(notes, 1): output += f"{i}. **{note.name}**\n" output += f" Path: `{note.path}`\n" output += f" Size: {note.size} bytes\n" if note.tags: output += f" Tags: {', '.join(note.tags)}\n" output += "\n" return output except VaultSecurityError as e: return f"Error: Security violation: {e}" except Exception as e: logger.exception("Error listing notes") return f"Error listing notes: {e}"
• src/obsidian_mcp/vault.py:175-247 (helper)

  Core implementation: scans vault directory (recursive or not), filters markdown files, extracts metadata (path, name, size, modified, optional tags), sorts by recency, returns list of NoteMetadata.
  def list_notes( self, folder: str = "", recursive: bool = True, limit: int | None = None, include_tags: bool = False, ) -> list[NoteMetadata]: """ List notes in the vault. Args: folder: Subfolder to list (empty for root) recursive: Include subfolders limit: Maximum number of results include_tags: Whether to extract tags (slower) Returns: List of note metadata """ start_path = self.vault_path if folder: start_path = self._validate_path(folder) notes: list[NoteMetadata] = [] count = 0 max_count = limit or self.config.max_results pattern = "**/*" if recursive else "*" for file_path in start_path.glob(pattern): if count >= max_count: break if not file_path.is_file(): continue if self._is_excluded(file_path): continue if file_path.suffix not in self.config.file_extensions: continue relative_path = str(file_path.relative_to(self.vault_path)) stats = file_path.stat() # Read file to extract tags (only if requested) if include_tags: try: content = file_path.read_text(encoding="utf-8") frontmatter, _ = self._parse_frontmatter(content) tags = self._extract_tags(content, frontmatter) except (OSError, UnicodeDecodeError, yaml.YAMLError) as e: logger.debug(f"Failed to extract tags from {file_path}: {e}") tags = [] else: tags = [] notes.append( NoteMetadata( path=relative_path, name=file_path.stem, extension=file_path.suffix, size=stats.st_size, modified=stats.st_mtime, tags=tags, ) ) count += 1 # Sort by modification time (newest first) notes.sort(key=lambda n: n.modified, reverse=True) return notes
• src/obsidian_mcp/server.py:232-232 (registration)

  Tool registration decorator specifying the name 'list_notes' and description.
  @mcp.tool(name="list_notes", description="List notes in the vault with optional filters")