# awkoy/notion-mcp-server architecture

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

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

## Overview

##### Project Type & Purpose
- This is a backend server application built in TypeScript that implements the Model Context Protocol (MCP) allowing AI assistants to interact with Notion’s API. Its purpose is to provide a complete set of tools and endpoints to read, create, and modify Notion content (pages, blocks, databases, comments, and users).

##### File Structure
- Key top-level files: Dockerfile, package.json, tsconfig.json, and README.md signal that this is a Node/TypeScript project, container-ready with Docker.
- The src folder is subdivided into:
- config – for application settings (src/config/index.ts)
- schema – for validating and defining data structures (a collection of schema files like blocks, pages, users, etc.)
- server – containing the server entry point (src/server/index.ts)
- services – abstracts integration logic (e.g., src/services/notion.ts, which calls the Notion API)
- tools – a rich set of utility modules for CRUD and batch operations on Notion objects (e.g., createPage, updateBlock, batch operations)
- types – TypeScript definitions that likely match the schema for blocks, users, comments, etc.
- utils – common error handling and utility functionality.

##### Reading the README for Additional Insights
- The README confirms the tool-based operations available alongside detailed documentation of various endpoints (page management, database operations, block operations, comments, and user management).
- It specifies integration aspects (e.g., Cursor, Claude Desktop integrations) and provides setup instructions, emphasizing that this is a production-ready MCP server.
- Technical details mention usage of TypeScript, the official Notion API client, and MCP SDK, which hints at middleware and modular design principles.

a. Server/Application Layer:
- Central server entry point (src/server/index.ts) that receives incoming requests or commands from MCP client integrations.
- Configuration loading (src/config) that sets up environment-specific variables (e.g., NOTION_TOKEN, NOTION_PAGE_ID).

b. Schema & Data Validation Layer:

c. Service Layer:
- Notion Service (src/services/notion.ts) which encapsulates the calls to Notion’s API, handling connection details and authentication.

d. Tools/Operations Layer:
- Enumerate tools (in src/tools) as modular components responsible for various Notion operations:
- Page operations (createPage, updatePageProperties, archive/restore)
- Database operations (createDatabase, queryDatabase, updateDatabase)
- Block operations (retrieve, update, delete, batch operations)
- Comment and user management tools.
- This layer serves as the functional connectors between the server’s API endpoints and the external Notion API.

e. Type Definitions & Utilities:
- A block for types (src/types) and utilities (src/utils) that support error handling and shared functionality across modules.

##### Relationships & Interactions
- Incoming requests first hit the Server Layer.
- Requests are forwarded to the appropriate tool based on the requested operation (e.g., creating a page, updating a block).
- The tool modules use the Notion Service to interact with Notion’s API.
- The Schema layer validates data before and after communication with Notion.
- How configurations (from src/config) and environmental variables (set via Dockerfile and .env, as noted in the README) feed into the server’s operation.

##### Architectural Patterns & Technologies
- Point out the modular design that separates concerns: server operations vs. business logic (tools/services) vs. schema definition/validation.
- Use of TypeScript for type safety, the Notion API client for external communication, and MCP SDK for protocol compliance.
- Possible use of dependency injection or configuration management patterns via the config directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    A["MCP Client (Cursor/Claude)"]:::external

    %% Supporting Components
    B["Server Entry Point"]:::server
    C["Configuration Management"]:::config
    D["Tools/Operations Layer"]:::tools
    E["Schema & Data Validation"]:::schema
    F["Notion Service"]:::service
    G["Type Definitions"]:::types
    H["Utilities & Error Handling"]:::utils
    I["Notion API"]:::external

    %% Flow connections
    A -->|"sendsRequest"| B
    C -->|"loadsConfig"| B
    B -->|"routesRequest"| D
    D -->|"validateInput"| E
    E -->|"validatedData"| D
    D -->|"callsService"| F
    F -->|"interactsWith"| I
    D -->|"handlesErrors"| H
    G -.->|"typeSafety"| E
    G -.->|"typeSafety"| D

    %% Click Events
    click B "https://github.com/awkoy/notion-mcp-server/blob/main/src/server/index.ts"
    click C "https://github.com/awkoy/notion-mcp-server/blob/main/src/config/index.ts"
    click E "https://github.com/awkoy/notion-mcp-server/tree/main/src/schema"
    click F "https://github.com/awkoy/notion-mcp-server/blob/main/src/services/notion.ts"
    click D "https://github.com/awkoy/notion-mcp-server/tree/main/src/tools"
    click G "https://github.com/awkoy/notion-mcp-server/tree/main/src/types"
    click H "https://github.com/awkoy/notion-mcp-server/tree/main/src/utils"

    %% Styles for colors and shapes
    classDef external fill:#f9f,stroke:#333,stroke-width:2px;
    classDef server fill:#bbf,stroke:#333,stroke-width:2px;
    classDef config fill:#ff9,stroke:#333,stroke-width:2px;
    classDef tools fill:#cfc,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef schema fill:#fc9,stroke:#333,stroke-width:2px;
    classDef service fill:#9f9,stroke:#333,stroke-width:2px;
    classDef types fill:#cff,stroke:#333,stroke-width:2px;
    classDef utils fill:#ffc,stroke:#333,stroke-width:2px;
```
