# rwb3n/obsidian-mcp architecture

> Architecture diagram of the GitHub repository rwb3n/obsidian-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rwb3n/obsidian-mcp
- Repository: https://github.com/rwb3n/obsidian-mcp

## Overview

##### Main Components
- Server Core: Represented by the core Python scripts such as “main.py” (both in the project root and inside the obsidian_mcp_server folder), “mcp_server.py”, and “config.py”. This denotes the MCP server’s initialization and configuration logic, which processes environment variables and sets up the server.
- Utility/Service Layer: The “obsidian_mcp_server/utils” directory includes modules like “daily_notes.py”, “vault_reader.py”, “vault_search.py”, “vault_writer.py”, and “exceptions.py”. These encapsulate the specific business logic for note and metadata manipulation, search operations, and error management.
- Environment & Configuration: The use of a “.env” file (with .env.example as the template) and the “config.py” script indicate external configuration management (e.g., OMCP_VAULT_PATH and other optional settings).
- Client Integration: The README details integration patterns with MCP clients (e.g., Claude Desktop) via JSON configuration. This is an external component that communicates with the MCP server.

- Configuration Module (config.py) that reads the environment and initializes server settings.
- The main entry point scripts (“obsidian_mcp_server/main.py” and “mcp_server.py”) that start the server process.
- “Utility Modules” as helper components interacting with the Server Core for tasks such as:
- Reading from the vault (vault_reader.py)
- Writing to the vault (vault_writer.py and the duplicate vault_writer.py module)
- Managing daily notes (daily_notes.py)
- Searching and exception handling (vault_search.py and exceptions.py)

##### Architectural Patterns and Design Principles
- The architecture is essentially backend/server-oriented with a clear separation of configuration, business logic (MCP server), and utility functions (abstracting out vault operations).
- Modularity: the separation of concerns between the server core and its utility modules is crucial.
- While not a full microservices architecture, the components (client, server, utilities, external vault) are clearly delineated.
- The use of environment variables for configuration demonstrates the Twelve-Factor App principle (externalizing configuration).

##### Technologies and Frameworks
- It is implemented in Python with a virtual environment (see instructions for creating a .venv).
- Environment configuration is managed through a dedicated file (".env") and the config.py module.
- While a specific web framework isn’t mentioned explicitly, the script structure and the presence of a “uv.lock” file hint at a possible use of uvicorn for async HTTP serving. If that is the case, you might note that although not explicit in the tree, the project is packaged to be launched either directly (python obsidian_mcp_server/main.py) or by an external MCP client.

##### Final Details
- Every component is clearly annotated: include notes on what each module does (e.g., “Handles note search”, “Manages reading/writing to vault”).
- Keep the design detailed but organized; separating the server’s core functionalities from its utilities will provide clarity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    subgraph "External Components"
        CLIENT("MCP Client (e.g., Claude Desktop)"):::external
        VAULT("Obsidian Vault"):::datastore
    end

    %% Server Core Components
    subgraph "Server Core"
        subgraph "Entrypoints"
            ROOT_MAIN("Main.py (project root)"):::core
            INTERNAL_MAIN("Main.py (obsidian_mcp_server)"):::core
        end
        CONFIG("Config Module (config.py)"):::core
        MCP_INIT("MCP Server Init (mcp_server.py)"):::core
        subgraph "Vault Utilities"
            DAILY("Daily Notes (daily_notes.py)"):::utility
            READER("Vault Reader (vault_reader.py)"):::utility
            SEARCH("Vault Search (vault_search.py)"):::utility
            WRITER("Vault Writer (vault_writer.py)"):::utility
            EXCEPT("Exceptions (exceptions.py)"):::utility
            ALT_WRITER("Alternate Vault Writer (vault_writer.py)"):::utility
        end
    end

    %% Environment & Deployment Components
    subgraph "Environment & Deployment"
        ENV("Environment Settings (.env/.env.example)"):::configLayer
        DEPLOY("Deployment Tools (pyproject.toml, LICENSE, .gitignore, uv.lock)"):::deploy
    end

    %% Data Flow Connections
    CLIENT -->|"sendsRequests"| ROOT_MAIN
    CLIENT -->|"sendsRequests"| INTERNAL_MAIN
    ROOT_MAIN -->|"loadsConfig"| CONFIG
    INTERNAL_MAIN -->|"loadsConfig"| CONFIG
    ROOT_MAIN -->|"startsServer"| MCP_INIT
    INTERNAL_MAIN -->|"startsServer"| MCP_INIT
    MCP_INIT -->|"calls"| DAILY
    MCP_INIT -->|"calls"| READER
    MCP_INIT -->|"calls"| SEARCH
    MCP_INIT -->|"calls"| WRITER
    MCP_INIT -->|"handles"| EXCEPT
    MCP_INIT -->|"calls"| ALT_WRITER
    DAILY -->|"readsWrites"| VAULT
    READER -->|"reads"| VAULT
    SEARCH -->|"queries"| VAULT
    WRITER -->|"writes"| VAULT
    ALT_WRITER -->|"writes"| VAULT
    CONFIG --> ENV
    ROOT_MAIN --> DEPLOY
    INTERNAL_MAIN --> DEPLOY
    MCP_INIT --> DEPLOY

    %% Click Events for File/Directory Mappings
    click ROOT_MAIN "https://github.com/rwb3n/obsidian-mcp/blob/master/main.py"
    click INTERNAL_MAIN "https://github.com/rwb3n/obsidian-mcp/blob/master/obsidian_mcp_server/main.py"
    click MCP_INIT "https://github.com/rwb3n/obsidian-mcp/blob/master/obsidian_mcp_server/mcp_server.py"
    click CONFIG "https://github.com/rwb3n/obsidian-mcp/blob/master/obsidian_mcp_server/config.py"
    click DAILY "https://github.com/rwb3n/obsidian-mcp/blob/master/obsidian_mcp_server/utils/daily_notes.py"
    click READER "https://github.com/rwb3n/obsidian-mcp/blob/master/obsidian_mcp_server/utils/vault_reader.py"
    click SEARCH "https://github.com/rwb3n/obsidian-mcp/blob/master/obsidian_mcp_server/utils/vault_search.py"
    click WRITER "https://github.com/rwb3n/obsidian-mcp/blob/master/obsidian_mcp_server/utils/vault_writer.py"
    click EXCEPT "https://github.com/rwb3n/obsidian-mcp/blob/master/obsidian_mcp_server/utils/exceptions.py"
    click ALT_WRITER "https://github.com/rwb3n/obsidian-mcp/blob/master/obsidian_mcp_server/vault_writer.py"
    click ENV "https://github.com/rwb3n/obsidian-mcp/blob/master/.env.example"
    click DEPLOY "https://github.com/rwb3n/obsidian-mcp/blob/master/pyproject.toml"

    %% Styles
    classDef external fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef datastore fill:#99CCFF,stroke:#333,stroke-width:2px;
    classDef core fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef utility fill:#FFDD99,stroke:#333,stroke-width:2px;
    classDef configLayer fill:#CCFFFF,stroke:#333,stroke-width:2px;
    classDef deploy fill:#FFCCFF,stroke:#333,stroke-width:2px;
```
