# orbit-logistics/notion-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/orbit-logistics/notion-mcp-server
- Repository: https://github.com/orbit-logistics/notion-mcp-server

## Overview

##### Project type and purpose
- This is an open-source MCP (Model Context Protocol) server that mirrors the entire Notion API SDK as a collection of “tools.”
- Its purpose is to let LLM-based clients (e.g., Cursor, Claude Desktop) invoke Notion operations (pages, databases, blocks, comments, users, search) via a unified command-line MCP interface.

##### File structure
- Top-level files:
- package.json, tsconfig.json, README.md, .gitignore – define dependencies, build config, and documentation.
- src/index.ts – entry point that parses CLI args (Notion token) and starts the MCP server.
- src/notion/client.ts – wraps the Notion SDK client with authentication and configuration.
- src/tools – each subfolder (blocks, comments, database, pages, search, users) exports one or more tool definitions that call the Notion client.
- Each tool group has an index.ts that aggregates individual actions (e.g., create_block, list_comments).

##### Extract additional insights from README
- The server exposes itself over a standard MCP “command” interface invoked via `npx ... -t <token>`.
- Clients register this server in their config and then issue JSON-RPC or command-line calls that map to tools.
- No GUI or web server; it’s purely a CLI-driven TCP/stdin-stdout protocol process.

a. Main components
1. External LLM Clients (Cursor, Claude Desktop)
2. MCP Server Process (this project)
– CLI/Protocol Handler (src/index.ts)
– Tool Registry (utils/defineTool + tools/*)
– Notion Client Adapter (src/notion/client.ts)
3. Notion API Service (external HTTP REST)
b. Relationships & interactions
1. LLM Client → (stdin/stdout or JSON-RPC over TCP) → MCP Server
2. MCP Server parses instructions → dispatches to appropriate Tool
3. Tool invokes Notion Client Adapter → issues HTTP requests to Notion API
4. Notion API responds → flow back through Tool → MCP Server → LLM Client
c. Architectural patterns & design principles
– Modular “tool” pattern: each API endpoint is wrapped as a discrete, self-describing tool
– Single responsibility:
- index.ts handles CLI/protocol
- client.ts handles authentication/HTTP
- defineTool + tools handle mapping user intent to API calls
– Protocol abstraction: MCP acts as a thin layer decoupling LLM clients from Notion SDK details
d. Technologies & libraries
– TypeScript + ts-node (runtime)
– Notion SDK (`@notionhq/client`)
– Model Context Protocol (MCP) conventions
– Commander or similar CLI parser (implicit in index.ts)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External LLM Clients
    LLM["LLM Client<br/>(Cursor, Claude Desktop)"]:::external

    %% MCP Server Process
    subgraph "MCP Server Process"
        direction TB
        CLI["CLI/Protocol Handler"]:::core
        Utils["Tool Registry Utility"]:::util
        subgraph "Tool Registry"
            direction TB
            Blocks["Blocks Tools"]:::tool
            Comments["Comments Tools"]:::tool
            Database["Database Tools"]:::tool
            Pages["Pages Tools"]:::tool
            Search["Search Tools"]:::tool
            Users["Users Tools"]:::tool
        end
        AuthClient["Notion Client Adapter"]:::adapter
    end

    %% External Notion API
    NotionAPI["Notion API Service<br/>(REST)"]:::external

    %% Data Flows
    LLM -->|"stdin/stdout or JSON-RPC"| CLI
    CLI -->|"load token & parse commands"| Utils
    Utils -->|"register tools"| Blocks
    Utils -->|"register tools"| Comments
    Utils -->|"register tools"| Database
    Utils -->|"register tools"| Pages
    Utils -->|"register tools"| Search
    Utils -->|"register tools"| Users
    Blocks -->|"invoke action"| AuthClient
    Comments -->|"invoke action"| AuthClient
    Database -->|"invoke action"| AuthClient
    Pages -->|"invoke action"| AuthClient
    Search -->|"invoke action"| AuthClient
    Users -->|"invoke action"| AuthClient
    AuthClient -->|"HTTP request"| NotionAPI
    NotionAPI -->|"HTTP response"| AuthClient
    AuthClient -->|"return result"| Utils
    Utils -->|"dispatch response"| CLI
    CLI -->|"output result"| LLM

    %% Click Events
    click CLI "https://github.com/orbit-logistics/notion-mcp-server/blob/main/src/index.ts"
    click AuthClient "https://github.com/orbit-logistics/notion-mcp-server/blob/main/src/notion/client.ts"
    click Utils "https://github.com/orbit-logistics/notion-mcp-server/blob/main/src/utils/defineTool.ts"
    click Blocks "https://github.com/orbit-logistics/notion-mcp-server/blob/main/src/tools/blocks/index.ts"
    click Comments "https://github.com/orbit-logistics/notion-mcp-server/blob/main/src/tools/comments/index.ts"
    click Database "https://github.com/orbit-logistics/notion-mcp-server/blob/main/src/tools/database/index.ts"
    click Pages "https://github.com/orbit-logistics/notion-mcp-server/blob/main/src/tools/pages/index.ts"
    click Search "https://github.com/orbit-logistics/notion-mcp-server/blob/main/src/tools/search/index.ts"
    click Users "https://github.com/orbit-logistics/notion-mcp-server/blob/main/src/tools/users/index.ts"

    %% Styles
    classDef external fill:#f0f0f0,stroke:#999,stroke-width:1px,color:#333;
    classDef core fill:#ffebcc,stroke:#e38d00,stroke-width:2px,color:#333;
    classDef util fill:#e0f7fa,stroke:#007c91,stroke-width:2px,color:#004d58;
    classDef tool fill:#e8f5e9,stroke:#2e7d32,stroke-width:1.5px,color:#1b5e20;
    classDef adapter fill:#fff3e0,stroke:#fb8c00,stroke-width:2px,color:#e65100;
```
