README - obsidian-api-mcp-server by pmmvr

Obsidian MCP Server

An MCP (Model Context Protocol) server that enables AI agents to perform sophisticated knowledge discovery and analysis across your Obsidian vault through the Local REST API plugin.

Why This Matters

This server transforms your Obsidian vault into a powerful knowledge base for AI agents, enabling complex multi-step workflows like:

"Retrieve notes from my 'Projects/Planning' folder containing 'roadmap' or 'timeline' in titles, created after April 1st, then analyze them for any blockers or dependencies and present a consolidated risk assessment with references to the source notes"
"Find all notes tagged with 'research' or 'analysis' from the last month, scan their content for incomplete sections or open questions, then cross-reference with my 'Team/Expertise' notes to suggest which colleagues could help address each gap"
"Get the complete content of meeting notes from 'Leadership/Quarterly' containing 'budget' or 'headcount', analyze them for action items assigned to my department, and create a chronological timeline with source note references"

The server's advanced filtering, regex support, and full content retrieval capabilities allow agents to perform nuanced knowledge work that would take hours manually.

Prerequisites

Install the Obsidian Local REST API plugin in your Obsidian vault
Configure and enable the plugin in Obsidian settings
Note the API URL (default: https://localhost:27124) and API key if you've set one

Installation

From PyPI (Recommended)

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

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

Add to MCP Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "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"
      }
    }
  }
}

From Source (Development)

# 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 .

Configuration

Set environment variables for the Obsidian API:

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

Important Security Note: Avoid hardcoding your OBSIDIAN_API_KEY directly into scripts or committing it to version control. Consider using a .env file (which is included in the .gitignore of this project) and a library like python-dotenv to manage your API key, or use environment variables managed by your operating system or shell.

Note: The server defaults to HTTPS and disables SSL certificate verification for self-signed certificates commonly used with local Obsidian instances. For HTTP connections, set OBSIDIAN_API_URL="http://localhost:27123".

Usage

Run the MCP server:

obsidian-mcp

Available Tools

The server provides three powerful tools:

search_vault - Advanced search with flexible filters and full content retrieval:
- query - Text or regex search across note content (optional)
- query_type - Search type: "text" (default) or "regex"
- search_in_path - Limit search to specific folder path
- title_contains - Filter by text in note titles (string, array, or JSON string)
- title_match_mode - How to match multiple terms: "any" (OR) or "all" (AND)
- tag - Filter by tag (string, array, or JSON string - searches frontmatter and inline #tags)
- tag_match_mode - How to match multiple tags: "any" (OR) or "all" (AND)
- context_length - Amount of content to return (set high for full content)
- include_content - Boolean to retrieve complete content of all matching notes
- created_since/until - Filter by creation date
- modified_since/until - Filter by modification date
- page_size - Results per page
- max_matches_per_file - Limit matches per note
Key Features:
- When no query is provided, automatically returns full content for filter-only searches
- include_content=True forces full content retrieval for any search
- Supports regex patterns for complex text matching (OR conditions, case-insensitive search, etc.)
get_note_content - Retrieve complete content and metadata of a specific note by path
browse_vault_structure - Navigate vault directory structure efficiently:
- path - Directory to browse (defaults to vault root)
- include_files - Boolean to include files (default: False, folders only for speed)
- recursive - Boolean to browse all nested directories

Example Use Cases

Basic Searches

Find notes by title in a specific folder:

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

Find notes with multiple title terms (OR logic):

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

Find notes with ALL title terms (AND logic):

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

Get all recent notes with full content:

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

Text search with context:

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

Search by tag:
```
search_vault(
  tag="project"
)
```

Regex search for OR conditions:

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

Regex search for tasks assigned to specific people:

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

Advanced Multi-Step Workflows

These examples demonstrate how agents can chain together sophisticated knowledge discovery tasks:

Strategic Project Analysis:

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

Agent can then analyze dependencies, identify risks, and recommend resource allocation

Meeting Action Item Mining:

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

Agent scans content for action items, extracts assignments, and creates chronological tracking

Research Gap Analysis:

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

Agent identifies knowledge gaps and suggests team members who could help

Vault Structure Exploration:

# Quick organizational overview
browse_vault_structure(recursive=True)

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

Tag-Based Knowledge Mapping:

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

Development

# 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

License

This project is licensed under the MIT License - see the file for details.