NotionMCP Light

Integrations

  • Provides bidirectional conversion between Markdown format and Notion's block structure, with support for elements like headers, allowing seamless content transfer between Markdown files and Notion.

  • Allows synchronization between Markdown files and Notion pages/databases, supporting both uploading Markdown content to create or update Notion pages and downloading Notion pages as Markdown files.

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

  1. Create an account on Notion Developers and get an API token.
  2. 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

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.

-
security - not tested
A
license - permissive license
-
quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A Model Context Protocol server that synchronizes Markdown files with Notion pages without using LLM tokens, enabling direct interaction with Notion databases and pages through API calls.

  1. overview
    1. function
      1. install
        1. Installing dependencies
        2. Setting up Notion API Token
      2. How to use
        1. Starting the MCP Server
        2. Setting in Cline/Cursor
      3. How to use MCP Tools
        1. uploadMarkdown
        2. downloadMarkdown
      4. license

        Related MCP Servers

        • -
          security
          A
          license
          -
          quality
          A Model Context Protocol server that integrates with Notion's API to manage personal todo lists, allowing users to view, add, and update tasks directly from Claude.
          Last updated -
          3
          Python
          MIT License
        • -
          security
          F
          license
          -
          quality
          A Model Context Protocol server that enables Claude and other LLMs to interact with Notion workspaces, providing capabilities like searching, retrieving, creating and updating pages, as well as managing databases.
          Last updated -
          275
          2
          TypeScript
        • -
          security
          A
          license
          -
          quality
          A Model Context Protocol server that provides a standardized interface for interacting with Notion's API, enabling users to list databases, create pages, and search across their Notion workspace.
          Last updated -
          95
          Python
          MIT License
          • Apple
        • A
          security
          A
          license
          A
          quality
          A Model Context Protocol server that converts Markdown content to HTML format.
          Last updated -
          1
          2,781
          2
          TypeScript
          MIT License
          • Apple

        View all related MCP servers

        ID: mduc0221dl