notion-mcp-light

NotionMCP Light is a Model Context Protocol (MCP) server that synchronizes Markdown files and Notion pages using the Notion API. ## Overview This project was developed to address the inefficiencies of the official Notion Model Context Protocol (MCP) server (reading and writing Markdown block by block, consuming LLM tokens). It provides an unofficial MCP server that allows direct synchronization of Markdown files and Notion pages/databases via the API without using tokens. ## Features - **Markdown → Notion** - Recognizes H1 as the page title - Creates Notion pages or database pages from Markdown content - Allows specifying a database ID - Directly uses the Notion API (token not used) - **Notion → Markdown** - Converts specified pages or database pages to Markdown format - Outputs the title as H1 - Converts block structure to Markdown - Saves to file - **MCP Server Support** - Complies with Model Context Protocol (MCP) - Provides endpoints callable from AI tools like Cursor and Cline - Operates based on JSON-RPC over stdio ## Installation ### Install Dependencies ```bash # If uv is not installed, install it first # pip install uv # Install dependencies uv sync ``` ### Set Up Notion API Token 1. Create an account at [Notion Developers](https://developers.notion.com/) and obtain an API token. 2. Set it as an environment variable or create a `.env` file to set the token. ```bash # Example .env file NOTION_TOKEN=your_notion_api_token ``` ## Usage ### Start MCP Server #### Using uv (recommended) ```bash uv run python -m src.main ``` Or, if specifying the token directly: ```bash uv run python -m src.main --token your_notion_api_token ``` #### Using regular Python ```bash python -m src.main ``` Or, if specifying the token directly: ```bash python -m src.main --token your_notion_api_token ``` ### Configuration in Cline/Cursor To use NotionMCP Light with AI coding tools like Cline/Cursor/Claude Code, add the following configuration to the JSON file for MCP server settings of each tool: ```json { "mcpServers": { "notion-mcp-light": { "command": "uv", "args": [ "run", "--directory", "/path/to/notion-mcp-light", "-m", "src.main" ], "env": { "NOTION_TOKEN": "your_notion_api_token" } } } } ``` Replace `/path/to/notion-mcp-light` with the installation directory of NotionMCP Light and `your_notion_api_token` with your Notion API token. ## Using MCP Tools NotionMCP Light provides the following MCP tools: ### uploadMarkdown Uploads a Markdown file and creates it as a Notion page. ```json { "jsonrpc": "2.0", "method": "uploadMarkdown", "params": { "filepath": "path/to/markdown.md", "database_id": "optional_database_id", "page_id": "optional_parent_page_id" }, "id": 1 } ``` ### downloadMarkdown Downloads a Notion page and saves it as a Markdown file. ```json { "jsonrpc": "2.0", "method": "downloadMarkdown", "params": { "page_id": "notion_page_id", "output_path": "path/to/output.md" }, "id": 2 } ``` ## License This project is published under the MIT license. Please refer to the [LICENSE](LICENSE) file for details.