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")