Skip to main content
Glama
deenesjakoruzh
pmmvr

Obsidian MCP Server

by pmmvr
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Obsidian MCP Server

Ein MCP-Server (Model Context Protocol), der es KI-Agenten ermöglicht, über das Local REST API-Plugin anspruchsvolle Wissensentdeckungen und -analysen in Ihrem Obsidian-Tresor durchzuführen.

Warum das wichtig ist

Dieser Server verwandelt Ihren Obsidian-Tresor in eine leistungsstarke Wissensdatenbank für KI-Agenten und ermöglicht komplexe mehrstufige Arbeitsabläufe wie:

  • „Rufen Sie Notizen aus meinem Ordner „Projekte/Planung“ ab, die „Roadmap“ oder „Zeitleiste“ in der Überschrift enthalten und nach dem 1. April erstellt wurden. Analysieren Sie sie anschließend auf etwaige Blockaden oder Abhängigkeiten und präsentieren Sie eine konsolidierte Risikobewertung mit Verweisen auf die Quellnotizen.“

  • „Suchen Sie alle mit ‚Forschung‘ oder ‚Analyse‘ gekennzeichneten Notizen des letzten Monats, durchsuchen Sie deren Inhalt nach unvollständigen Abschnitten oder offenen Fragen und vergleichen Sie sie dann mit meinen ‚Team/Expertise‘-Notizen, um vorzuschlagen, welche Kollegen bei der Behebung der jeweiligen Lücken helfen könnten.“

  • „Holen Sie sich den kompletten Inhalt der Besprechungsnotizen aus ‚Leadership/Quarterly‘ mit den Angaben ‚Budget‘ oder ‚Personalbestand‘, analysieren Sie diese auf die meiner Abteilung zugewiesenen Aktionspunkte und erstellen Sie eine chronologische Zeitleiste mit Quellenangaben.“

Dank der erweiterten Filterung, der Regex-Unterstützung und der umfassenden Inhaltsabruffunktionen des Servers können Agenten differenzierte Wissensarbeit leisten, die manuell Stunden dauern würde.

Related MCP server: Obsidian Local REST API MCP Server

Voraussetzungen

  1. Installieren Sie das Obsidian Local REST API- Plugin in Ihrem Obsidian-Tresor

  2. Konfigurieren und aktivieren Sie das Plugin in den Obsidian-Einstellungen

  3. Notieren Sie sich die API-URL (Standard: https://localhost:27124 ) und den API-Schlüssel, falls Sie einen festgelegt haben

Installation

Von PyPI (empfohlen)

# Install from PyPI
pip install obsidian-api-mcp-server

# Or with uv
uv pip install obsidian-api-mcp-server

Zur MCP-Konfiguration hinzufügen

Fügen Sie Ihrer MCP-Clientkonfiguration (z. B. Claude Desktop) Folgendes hinzu:

{
  "mcpServers": {
    "obsidian-api-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "obsidian-api-mcp-server>=1.0.1",
        "obsidian-api-mcp"
      ],
      "env": {
        "OBSIDIAN_API_URL": "https://localhost:27124",
        "OBSIDIAN_API_KEY": "your-api-key-here"
      }
    }
  }
}

Aus der Quelle (Entwicklung)

# Clone the repository
git clone https://github.com/pmmvr/obsidian-api-mcp-server
cd obsidian-api-mcp-server

# Install with uv
uv pip install -e .

# Or with pip
pip install -e .

Konfiguration

Legen Sie Umgebungsvariablen für die Obsidian-API fest:

# Required: Obsidian API URL (HTTPS by default)
export OBSIDIAN_API_URL="https://localhost:27124"  # Default

# Optional: API key if you've configured authentication
export OBSIDIAN_API_KEY="your-api-key-here"

Wichtiger Sicherheitshinweis : Vermeiden Sie es, Ihren OBSIDIAN_API_KEY direkt in Skripte einzubinden oder ihn der Versionskontrolle zu übergeben. Verwenden Sie eine .env Datei (die in der .gitignore Datei dieses Projekts enthalten ist) und eine Bibliothek wie python-dotenv zur Verwaltung Ihres API-Schlüssels oder verwenden Sie Umgebungsvariablen, die von Ihrem Betriebssystem oder Ihrer Shell verwaltet werden.

Hinweis : Der Server verwendet standardmäßig HTTPS und deaktiviert die SSL-Zertifikatsprüfung für selbstsignierte Zertifikate, die häufig bei lokalen Obsidian-Instanzen verwendet werden. Für HTTP-Verbindungen setzen Sie OBSIDIAN_API_URL="http://localhost:27123" .

Verwendung

Führen Sie den MCP-Server aus:

obsidian-mcp

Verfügbare Tools

Der Server bietet drei leistungsstarke Tools:

  1. search_vault – Erweiterte Suche mit flexiblen Filtern und vollständigem Inhaltsabruf:

    • query – Text- oder Regex-Suche im gesamten Notizinhalt (optional)

    • query_type – Suchtyp: „Text“ (Standard) oder „regulärer Ausdruck“

    • search_in_path – Suche auf bestimmten Ordnerpfad beschränken

    • title_contains – Filtern nach Text in Notiztiteln (Zeichenfolge, Array oder JSON-Zeichenfolge)

    • title_match_mode – So werden mehrere Begriffe abgeglichen: „any“ (OR) oder „all“ (AND)

    • tag – Filtern nach Tag (Zeichenfolge, Array oder JSON-Zeichenfolge – durchsucht Frontmatter und Inline-#Tags)

    • tag_match_mode – So werden mehrere Tags abgeglichen: „any“ (OR) oder „all“ (AND)

    • context_length – Menge des zurückzugebenden Inhalts (hoch einstellen für vollständigen Inhalt)

    • include_content – Boolescher Wert zum Abrufen des vollständigen Inhalts aller übereinstimmenden Notizen

    • created_since/until – Filtern nach Erstellungsdatum

    • modified_since/until – Filtern nach Änderungsdatum

    • page_size – Ergebnisse pro Seite

    • max_matches_per_file – Übereinstimmungen pro Notiz begrenzen

    Hauptmerkmale :

    • Wenn keine query angegeben ist, wird bei Nur-Filter-Suchen automatisch der vollständige Inhalt zurückgegeben.

    • include_content=True erzwingt den vollständigen Inhaltsabruf für jede Suche

    • Unterstützt Regex-Muster für komplexe Textübereinstimmungen (ODER-Bedingungen, Suche ohne Berücksichtigung der Groß-/Kleinschreibung usw.)

  2. get_note_content - Vollständigen Inhalt und Metadaten einer bestimmten Notiz über den Pfad abrufen

  3. browse_vault_structure – Effizientes Navigieren in der Tresor-Verzeichnisstruktur:

    • path – Zu durchsuchendes Verzeichnis (standardmäßig das Stammverzeichnis des Tresors)

    • include_files – Boolescher Wert zum Einschließen von Dateien (Standard: False, Ordner nur aus Geschwindigkeitsgründen)

    • recursive - Boolescher Wert zum Durchsuchen aller verschachtelten Verzeichnisse

Beispiel-Anwendungsfälle

Einfache Suchen

  1. Suchen Sie in einem bestimmten Ordner nach Notizen nach Titel:

    search_vault(
  search_in_path="Work/Projects/",
  title_contains="meeting"
)

  2. Notizen mit mehreren Titelbegriffen finden (ODER-Logik):

    search_vault(
  title_contains=["foo", "bar", "fizz", "buzz"],
  title_match_mode="any"  # Default
)

  3. Notizen mit ALLEN Titelbegriffen (UND-Logik) finden:

    search_vault(
  title_contains=["project", "2024"],
  title_match_mode="all"
)

  4. Alle aktuellen Notizen mit vollständigem Inhalt abrufen:

    search_vault(
  modified_since="2025-05-20",
  include_content=True
)

  5. Textsuche mit Kontext:

    search_vault(
  query="API documentation",
  search_in_path="Engineering/",
  context_length=500
)

  6. Suche nach Tag:

    search_vault(
  tag="project"
)

  7. Regex-Suche nach ODER-Bedingungen:

    search_vault(
  query="foo|bar",
  query_type="regex",
  search_in_path="Projects/"
)

  8. Regex-Suche nach Aufgaben, die bestimmten Personen zugewiesen sind:

    search_vault(
  query="(TODO|FIXME|ACTION).*@(alice|bob)",
  query_type="regex",
  search_in_path="Work/Meetings/"
)

Erweiterte mehrstufige Workflows

Diese Beispiele zeigen, wie Agenten anspruchsvolle Aufgaben zur Wissensermittlung miteinander verketten können:

  1. Strategische Projektanalyse:

    # Step 1: Get all project documentation
search_vault(
  search_in_path="Projects/Infrastructure/",
  title_contains=["planning", "requirements", "architecture"],
  title_match_mode="any",
  include_content=True
)

# Step 2: Find related technical discussions
search_vault(
  tag=["infrastructure", "technical-debt"],
  tag_match_mode="any",
  modified_since="2025-04-01",
  include_content=True
)

    Der Agent kann dann Abhängigkeiten analysieren, Risiken identifizieren und eine Ressourcenzuweisung empfehlen

  2. Mining von Meeting-Aktionselementen:

# Get all recent meeting notes with full content
search_vault(
  search_in_path="Meetings/",
  title_contains=["standup", "planning", "retrospective"],
  title_match_mode="any",
  created_since="2025-05-01",
  include_content=True
)

Der Agent durchsucht Inhalte nach Aktionselementen, extrahiert Aufgaben und erstellt eine chronologische Verfolgung

  1. Forschungslückenanalyse:

# Find research notes with questions or gaps
search_vault(
  query="(TODO|QUESTION|INVESTIGATE|UNCLEAR)",
  query_type="regex",
  tag=["research", "analysis"],
  tag_match_mode="any",
  include_content=True
)

# Cross-reference with team expertise
search_vault(
  search_in_path="Team/",
  tag=["expertise", "skills"],
  tag_match_mode="any",
  include_content=True
)

Der Agent identifiziert Wissenslücken und schlägt Teammitglieder vor, die helfen könnten

  1. Erkundung der Tresorstruktur:

# Quick organizational overview
browse_vault_structure(recursive=True)

# Deep dive into specific areas
browse_vault_structure(
  path="Projects/CurrentSprint/",
  include_files=True,
  recursive=True
)

  1. Tag-basiertes Wissensmapping:

# Find notes with multiple tags (AND logic)
search_vault(
  tag=["project", "urgent"],
  tag_match_mode="all",
  include_content=True
)

# Find notes with any relevant tags (OR logic)
search_vault(
  tag=["architecture", "design", "implementation"],
  tag_match_mode="any",
  modified_since="2025-04-15"
)

Entwicklung

# Install with test dependencies
uv pip install -e ".[test]"

# Run the server
python -m obsidian_mcp.server

# Run tests
uv run behave features/blackbox_tests.feature
# Or use the test runner
python run_tests.py

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – Einzelheiten finden Sie in der Datei LICENSE .

Available Tools

3 tools
browse_vault_structureA
Read-only
Browse vault directory structure.

Args:
    path: Path to browse from (defaults to vault root)
    include_files: Include files in listing (default: False, folders only)
    recursive: List nested contents recursively
NameRequiredDescriptionDefault
include_filesNo
pathNo
recursiveNo

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true and openWorldHint=false, indicating this is a safe read operation with deterministic results. The description adds valuable context about default behaviors (browsing from vault root, folders-only by default) and the recursive option, which goes beyond what annotations provide. No contradictions with annotations exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly structured: a clear purpose statement followed by a bullet-point style explanation of each parameter. Every sentence earns its place, with no wasted words. The information is front-loaded with the core purpose first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a directory browsing tool with 3 parameters, no output schema, and good annotations, the description covers the essential behavior and parameters adequately. However, it doesn't describe the return format (e.g., what structure is returned, error conditions), which would be helpful given the lack of output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description carries full burden for parameter meaning. It successfully explains all three parameters: 'path' (starting location with default), 'include_files' (files inclusion toggle with default), and 'recursive' (nested listing). This compensates well for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Browse') and resource ('vault directory structure'), making the purpose immediately understandable. It distinguishes from sibling tools like 'get_note_content' (which retrieves content) and 'search_vault' (which searches), but doesn't explicitly mention these distinctions in the description itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for exploring directory structure rather than retrieving content or searching, but doesn't provide explicit guidance on when to use this tool versus alternatives like 'search_vault'. The parameter descriptions suggest default behaviors (folders only, non-recursive), which gives some contextual hints.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_note_contentA
Read-only
Get the full content and metadata of a specific note by path.

Args:
    path: Full path to the note within the vault
NameRequiredDescriptionDefault
pathYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=true and openWorldHint=false, indicating a safe, read-only operation with a closed world. The description adds context by specifying 'full content and metadata,' which hints at the return format, but doesn't detail aspects like error handling, rate limits, or auth needs. No contradiction with annotations exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by a concise parameter explanation. Every sentence earns its place with no wasted words, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (1 parameter, no output schema), annotations cover safety, and the description adds parameter semantics and purpose. However, it lacks details on return values, error cases, or how it differs from siblings, leaving some gaps for an AI agent to infer usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and 1 parameter, the description compensates by explaining 'path: Full path to the note within the vault,' adding meaning beyond the bare schema. It clarifies the parameter's purpose and format, though it could provide more examples or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get the full content and metadata of a specific note by path.' It specifies the verb ('Get'), resource ('note'), and scope ('full content and metadata'), though it doesn't explicitly differentiate from sibling tools like 'browse_vault_structure' or 'search_vault' beyond the 'specific note by path' aspect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by specifying 'by path,' suggesting it's for retrieving a known note, but it doesn't provide explicit guidance on when to use this tool versus alternatives like 'search_vault' for unknown notes or 'browse_vault_structure' for exploring. No exclusions or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_vaultA
Read-only
Search Obsidian vault for notes matching criteria.

Args:
    query: Text or regex pattern to search for
    query_type: "text" or "regex" 
    search_in_path: Limit search to specific folder
    title_contains: Filter by title (string or array)
    title_match_mode: "any" or "all" for multiple title terms
    tag: Filter by tag (string, array, or JSON string like title_contains)
    tag_match_mode: "any" or "all" for multiple tag terms
    context_length: Characters of context around matches
    include_content: Return full note content
    modified_since/until: Filter by modification date (YYYY-MM-DD)
    created_since/until: Filter by creation date (YYYY-MM-DD)
    page_size/page: Pagination controls
    max_matches_per_file: Limit matches per file
NameRequiredDescriptionDefault
context_lengthNo
created_sinceNo
created_untilNo
include_contentNo
max_matches_per_fileNo
modified_sinceNo
modified_untilNo
pageNo
page_sizeNo
queryNo
query_typeNotext
search_in_pathNo
tagNo
tag_match_modeNoany
title_containsNo
title_match_modeNoany

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=false, indicating this is a safe read operation with limited scope. The description adds useful context about what gets searched ('notes') and the types of criteria available, but doesn't disclose behavioral aspects like performance characteristics, rate limits, or error conditions. With annotations covering the safety profile, this earns a baseline score.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose statement followed by a comprehensive parameter list. Every sentence earns its place by providing essential information. It could be slightly more concise by grouping related parameters, but overall it's efficient and front-loaded with the core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex search tool with 16 parameters and no output schema, the description does a good job explaining inputs but has gaps. It doesn't describe the return format (what the search results look like), error conditions, or performance considerations. The parameter explanations are excellent, but without output information or behavioral context, completeness is limited.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage (titles only, no descriptions), the description carries the full burden of explaining parameters. It provides detailed semantic information for all 16 parameters, including data types, formats, and usage examples (e.g., 'YYYY-MM-DD' for dates, 'text' or 'regex' for query_type). This fully compensates for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Search Obsidian vault for notes matching criteria.' This specifies the verb ('search'), resource ('Obsidian vault'), and target ('notes matching criteria'). However, it doesn't explicitly differentiate from sibling tools like 'browse_vault_structure' or 'get_note_content', which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There's no mention of sibling tools like 'browse_vault_structure' (for exploring structure) or 'get_note_content' (for retrieving specific note content), nor any context about when search is appropriate versus other approaches.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedbrowse_vault_structure
    • First observedget_note_content
    • First observedsearch_vault
Deploy Server
Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

A3.7/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: browse_vault_structure is for exploring the file hierarchy, get_note_content retrieves a specific note's details, and search_vault performs complex queries across the vault. There is no overlap in functionality, making it easy for an agent to select the right tool.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case: browse_vault_structure, get_note_content, and search_vault. The naming is predictable and readable, with no deviations in style or convention.

Tool Count3/5

With only 3 tools, the server feels thin for managing an Obsidian vault, which typically involves operations like creating, updating, or deleting notes. While the tools cover browsing, reading, and searching, the lack of write operations limits the scope, making it borderline for the domain.

Completeness2/5

The tool set is severely incomplete for an Obsidian vault management server. There are no tools for creating, updating, or deleting notes, which are core CRUD operations. This creates significant gaps that will likely cause agent failures when trying to perform basic note management tasks.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers