NotionMCP Light

NotionMCP Light is a Model Context Protocol (MCP) server that uses the Notion API to sync Markdown files with Notion pages.

overview

This project was developed to address the inefficiencies of Notion's official Model Context Protocol (MCP) server (which reads and writes Markdown in blocks and consumes LLM tokens). It provides an unofficial MCP server that does not consume tokens and can sync Markdown files directly with Notion's pages/database via API.

function

Markdown → Notion
- Recognize H1 as page title
- Create Markdown content as a Notion page or a database page
- Database ID can be specified
- Using the Notion API directly (no tokens)
Notion → Markdown
- Converts a given page or a page in a database to Markdown format.
- Output title as H1
- Convert block structure to Markdown
- Save to File
MCP server support
- Model Context Protocol (MCP) compliant
- Provides endpoints that can be called from AI tools such as Cursor and Cline
- JSON-RPC over stdio based

install

Installing dependencies

# uvがインストールされていない場合は先にインストール
# pip install uv

# 依存関係のインストール
uv sync

Setting up Notion API Token

Create an account on Notion Developers and get an API token.
You can set it in an environment variable or create a .env file and set the token.

# .envファイルの例
NOTION_TOKEN=your_notion_api_token

How to use

Starting the MCP Server

When using UV (recommended)

uv run python -m src.main

Or, if you want to specify the token directly:

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

If you use regular Python

python -m src.main

Or, if you want to specify the token directly:

python -m src.main --token your_notion_api_token

Setting in Cline/Cursor

To use NotionMCP Light with AI tools such as Cline/Cursor, add the following settings to your 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 installation directory of NotionMCP Light.

How to use MCP Tools

NotionMCP Light offers the following MCP tools:

uploadMarkdown

Upload your Markdown file and create it as a Notion page.

{
  "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 your Notion page and save it as a Markdown file.

{
  "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 file for details.