NotionMCP Light 中文版

NotionMCP Light 是一个使用 Notion API 实现 Markdown 文件与 Notion 页面同步的 Model Context Protocol (MCP) 服务器。

概要

为了解决官方 Notion MCP 服务器在处理 Markdown 内容时存在的低效问题（如以块为单位读取写入并消耗 LLM 令牌），我们开发了这个非官方的 MCP 服务器。它可以直接通过 API 实现 Markdown 文件与 Notion 页面或数据库之间的同步，而无需使用令牌。

功能

• Markdown → Notion

  • 将 H1 标题识别为页面标题
  • 将 Markdown 内容作为新的 Notion 页面或数据库条目创建
  • 支持指定目标数据库 ID
  • 直接调用 Notion API（无需令牌）

• Notion → Markdown

  • 将指定的页面或数据库条目转换为 Markdown 格式
  • 输出时将标题作为 H1 处理
  • 转换块结构为 Markdown 格式
  • 文件保存功能

• MCP 服务器兼容性

  • 遵循 Model Context Protocol (MCP) 规范
  • 支持从 AI 工具（如 Cursor、Cline）进行调用
  • 基于 stdio 的 JSON-RPC 实现

安装

安装依赖项

# 若未安装 uv，请先执行安装
# pip install uv

# 安装依赖项
uv sync

设置 Notion API 令牌

1. 在 Notion Developers 创建账户并获取 API 令牌。
2. 将令牌设置为环境变量，或通过 .env 文件进行配置。

# .env 文件示例
NOTION_TOKEN=your_notion_api_token

使用方法

启动 MCP 服务器

使用 uv（推荐）

uv run python -m src.main

或者直接指定令牌：

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

普通 Python 环境下

python -m src.main

或直接指定令牌：

python -m src.main --token your_notion_api_token

在 Cline/Cursor 中配置

在 Cline/Cursor 等 AI 工具中使用 NotionMCP Light，请在 mcp_settings.json 文件中添加以下内容：

"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": []
}

将 /path/to/notion-mcp-light 替换为 NotionMCP Light 的实际安装路径。

MCP 工具使用方法

NotionMCP Light 提供以下 MCP 工具：

uploadMarkdown

上传 Markdown 文件并创建 Notion 页面。

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