How awkoy/notion-mcp-server works
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.