How orbit-logistics/notion-mcp-server works
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)