notion-mcp-light

# NotionMCP Light NotionMCP Light is an unofficial 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, which reads and writes Markdown in block units and consumes LLM tokens. It provides an unofficial MCP server that directly synchronizes Markdown files and Notion pages/databases via the API without using tokens. ## Features - **Markdown → Notion** - Recognize H1 as page title - Create Markdown content as a Notion page or database page - Specify database ID - Directly use Notion API (no token usage) - **Notion → Markdown** - Convert specified page or database page to Markdown format - Output title as H1 - Convert block structure to Markdown - Save to file - **MCP Server Compliance** - Compliant with Model Context Protocol (MCP) - Provide endpoints callable from AI tools like Cursor and Cline - Operate based on JSON-RPC over stdio ## Installation ### Install Dependencies ```bash # Install uv if not already installed # pip install uv # Install dependencies uv sync ``` ### Configure Notion API Token 1. Create an account on [Notion Developers](https://developers.notion.com/) and obtain an API token. 2. Set the token as an environment variable or create a `.env` file. ```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, specify the token directly: ```bash uv run python -m src.main --token your_notion_api_token ``` #### Using Regular Python ```bash python -m src.main ``` Or, specify the token directly: ```bash python -m src.main --token your_notion_api_token ``` ### Configuration for 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: ```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 Upload a Markdown file and create 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 Download a Notion page and save 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 released under the MIT License. See the [LICENSE](LICENSE) file for details.