Obsidian MCP Server

Instructions

Implementation Reference

• src/obsidian_mcp/server.py:281-284 (registration)

  Registration of the get_backlinks MCP tool using the @mcp.tool decorator.

  @mcp.tool(
      name="get_backlinks",
      description="Get all notes that link to a specific note (incoming links)",
  )

• src/obsidian_mcp/server.py:285-322 (handler)

  MCP tool handler function for 'get_backlinks'. Performs input validation, calls the vault method, formats output, and handles errors.

  async def get_backlinks(path: str, limit: int | None = None) -> str:
      """
      Get all notes that link to this note.
  
      Args:
          path: Relative path to the note (e.g., "Projects/MCP.md")
          limit: Optional maximum number of notes to scan (recommended for large vaults)
  
      Returns:
          Formatted list of notes that link to this note
      """
      if not path or not path.strip():
          return "Error: Path cannot be empty"
      if len(path) > 1000:
          return "Error: Path too long"
  
      context = _get_context()
  
      try:
          backlinks = await context.vault.get_backlinks(path, limit=limit)
  
          if not backlinks:
              return f"No backlinks found for '{path}'"
  
          output = f"Found {len(backlinks)} note(s) linking to '{path}':\n\n"
          for i, link_path in enumerate(backlinks, 1):
              output += f"{i}. `{link_path}`\n"
  
          return output
  
      except FileNotFoundError:
          return f"Error: Note not found: {path}"
      except VaultSecurityError as e:
          return f"Error: Security violation: {e}"
      except Exception as e:
          logger.exception(f"Error getting backlinks for {path}")
          return f"Error getting backlinks: {e}"

• src/obsidian_mcp/vault.py:323-377 (handler)

  Core implementation of the backlinks functionality in the ObsidianVault class. Scans notes, extracts wikilinks, and finds incoming links to the target note.

  async def get_backlinks(self, relative_path: str, limit: int | None = None) -> list[str]:
      """
      Get all notes that link to this note.
  
      Warning: This method scans all notes in the vault (O(n) behavior) which can be slow
      for large vaults. Consider using the 'limit' parameter to cap the number of notes
      scanned, or wait for future versions with persistent link indexing for better performance.
  
      Args:
          relative_path: Path to the target note
          limit: Optional maximum number of notes to scan. If None, scans all notes but
                 logs a warning for large vaults (>1000 notes).
  
      Returns:
          List of note paths that link to this note
  
      Future: A persistent link index will be added to eliminate the O(n) scan overhead.
      """
      target_name = Path(relative_path).stem
      backlinks = []
  
      # Get list of notes to scan
      all_notes = list(self.list_notes(limit=10000))
      notes_to_scan = all_notes if limit is None else all_notes[:limit]
  
      # Warn if scanning large vault without limit
      if limit is None and len(all_notes) > 1000:
          logger.warning(
              f"get_backlinks scanning {len(all_notes)} notes without limit. "
              f"Consider using limit parameter for better performance on large vaults."
          )
  
      # Search through notes
      scanned = 0
      for note_meta in notes_to_scan:
          try:
              note = await self.read_note(note_meta.path)
              links = self._extract_links(note.content)
  
              # Check if any link resolves to target
              for link in links:
                  # Match by filename or full path
                  if link == target_name or link == relative_path.replace(".md", ""):
                      backlinks.append(note_meta.path)
                      break
  
              scanned += 1
              if limit and scanned >= limit:
                  break
          except Exception as e:
              logger.debug(f"Error checking backlinks in {note_meta.path}: {e}")
              continue
  
      return backlinks