Obsidian MCP Server

Instructions

Implementation Reference

• src/obsidian_mcp/server.py:516-567 (handler)

  Primary MCP tool handler for 'search_by_property'. Validates inputs, invokes the VaultSearch method, formats results as markdown list.

      name="search_by_property",
      description="Search for notes by frontmatter property (metadata field)",
  )
  async def search_by_property(property_name: str, property_value: str = "", limit: int = 50) -> str:
      """
      Search for notes by frontmatter property.
  
      Args:
          property_name: Name of the frontmatter property to search
          property_value: Optional value to match (empty to find all notes with this property)
          limit: Maximum number of results (default: 50)
  
      Returns:
          Formatted list of notes matching the property
      """
      if not property_name or not property_name.strip():
          return "Error: Property name cannot be empty"
      if limit <= 0 or limit > 1000:
          return "Error: Limit must be between 1 and 1000"
  
      context = _get_context()
  
      try:
          # Convert empty string to None for "any value" search
          value = property_value if property_value else None
          results = await context.search.search_by_property(property_name, value, limit=limit)
  
          if not results:
              if value:
                  return f"No notes found with property '{property_name}' = '{value}'"
              else:
                  return f"No notes found with property '{property_name}'"
  
          # Format results
          if value:
              output = f"Found {len(results)} note(s) with '{property_name}' = '{value}':\n\n"
          else:
              output = f"Found {len(results)} note(s) with property '{property_name}':\n\n"
  
          for i, result in enumerate(results, 1):
              output += f"{i}. **{result.name}**\n"
              output += f"   Path: `{result.path}`\n"
              if result.snippet:
                  output += f"   {result.snippet}\n"
              output += "\n"
  
          return output
  
      except Exception as e:
          logger.exception(f"Error searching by property: {property_name}")
          return f"Error searching by property: {e}"

• src/obsidian_mcp/search.py:199-264 (helper)

  Core implementation logic in VaultSearch class that scans notes, matches frontmatter properties, scores results, and returns SearchResult list.

  async def search_by_property(
      self, property_name: str, property_value: str | None = None, limit: int = 50
  ) -> list[SearchResult]:
      """
      Search for notes by frontmatter property.
  
      Args:
          property_name: Name of the frontmatter property
          property_value: Optional value to match (if None, matches any note with the property)
          limit: Maximum number of results
  
      Returns:
          List of search results
      """
      results: list[SearchResult] = []
      notes = self.vault.list_notes(limit=None)
  
      for note_meta in notes:
          if len(results) >= limit:
              break
  
          try:
              note = await self.vault.read_note(note_meta.path)
  
              if not note.frontmatter:
                  continue
  
              # Check if property exists
              if property_name not in note.frontmatter:
                  continue
  
              prop_val = note.frontmatter[property_name]
  
              # If no value specified, just match presence
              if property_value is None:
                  score = 1.0
              else:
                  # Check if value matches
                  if isinstance(prop_val, list):
                      # Check if value is in list
                      if property_value in prop_val or property_value in str(prop_val):
                          score = 2.0
                      else:
                          continue
                  elif str(prop_val).lower() == property_value.lower():
                      score = 5.0  # Exact match
                  elif property_value.lower() in str(prop_val).lower():
                      score = 2.0  # Partial match
                  else:
                      continue
  
              # Create snippet from frontmatter
              snippet = f"{property_name}: {prop_val}"
  
              results.append(
                  SearchResult(
                      path=note_meta.path, name=note_meta.name, score=score, snippet=snippet
                  )
              )
  
          except (OSError, UnicodeDecodeError) as e:
              logger.debug(f"Failed to read note {note_meta.path}: {e}")
              continue
  
      results.sort(key=lambda r: r.score, reverse=True)
      return results[:limit]

• src/obsidian_mcp/search.py:14-23 (schema)

  Dataclass defining the structure of search results used by search_by_property.

  @dataclass(slots=True, frozen=True)
  class SearchResult:
      """A search result with context (immutable)."""
  
      path: str
      name: str
      score: float
      snippet: str | None = None
      matched_tags: list[str] | None = None

• src/obsidian_mcp/server.py:516-519 (registration)

  MCP tool registration decorator specifying the tool name and description.

      name="search_by_property",
      description="Search for notes by frontmatter property (metadata field)",
  )
  async def search_by_property(property_name: str, property_value: str = "", limit: int = 50) -> str: