Notion Markdown

🚀 NotionMCP Light

NotionMCP Light is an unofficial Model Context Protocol (MCP) server that uses the Notion API to synchronize Markdown files with Notion pages. It aims to address the inefficiencies of the official Notion MCP server when handling Markdown content, such as reading and writing in block units and consuming LLM tokens. This server can directly synchronize Markdown files with Notion pages or databases via the API without using tokens.

🚀 Quick Start

To quickly get started with NotionMCP Light, follow the installation and setup steps below.

✨ Features

Markdown → Notion

• Recognize H1 headings as page titles.
• Create new Notion pages or database entries from Markdown content.
• Support specifying the target database ID.
• Directly call the Notion API without using tokens.

Notion → Markdown

• Convert specified pages or database entries to Markdown format.
• Treat titles as H1 headings in the output.
• Convert block structures to Markdown format.
• Provide file saving functionality.

MCP Server Compatibility

• Comply with the Model Context Protocol (MCP) specification.
• Support calls from AI tools such as Cursor and Cline.
• Implement JSON - RPC based on stdio.

📦 Installation

Install Dependencies

# If uv is not installed, install it first
# pip install uv

# Install dependencies
uv sync

Set Notion API Token

1. Create an account on Notion Developers and obtain an API token.
2. Set the token as an environment variable or configure it through a .env file.

# Example of .env file
NOTION_TOKEN=your_notion_api_token

💻 Usage Examples

Start the MCP Server

Using uv (Recommended)

uv run python -m src.main

Or specify the token directly:

uv run python -m src.main --token your_notion_api_token

In a Regular Python Environment

python -m src.main

Or specify the token directly:

python -m src.main --token your_notion_api_token

Configure in Cline/Cursor

To use NotionMCP Light in AI tools like Cline or Cursor, add the following content to the mcp_settings.json file:

"notion-mcp-light": {
  "command": "uv",
  "args": [
    "run",
    "--directory",
    "/path/to/notion-mcp-light",
    "python",
    "-m",
    "src.main"
  ],
  "env": {
    "NOTION_TOKEN": "your_notion_api_token"
  },
  "disabled": false,
  "alwaysAllow": []
}

Replace /path/to/notion-mcp-light with the actual installation path of NotionMCP Light.

MCP Tool Usage

uploadMarkdown

Upload a Markdown file and create a Notion page.

{
  "jsonrpc": "2.0",
  "method": "uploadMarkdown",
  "params": {
    "filepath": "path/to/markdown.md"
  }
}