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.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

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.

Related MCP Servers

Notion MCP
Badhansen
-
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 -
13
Python
MIT License
Notion MCP Server
SAhmadUmass
-
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
Notion MCP Server
ccabanillas
-
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
markdown-to-html
fashionzzZ
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

View all related MCP servers

NotionMCP Light

NotionMCP Light

overview

function

install

Installing dependencies

Setting up Notion API Token

How to use

Starting the MCP Server

When using UV (recommended)

If you use regular Python

Setting in Cline/Cursor

How to use MCP Tools

uploadMarkdown

downloadMarkdown

license

Related MCP Servers

Notion MCP

Notion MCP Server

Notion MCP Server

markdown-to-html

New MCP Servers

MCP directory API