NotionMCP Light

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

概述

该项目旨在解决官方 Model Context Protocol (MCP) 服务器在处理 Markdown 文件时存在的低效问题（即按块读写 Markdown 并消耗 LLM 令牌）。它提供了一个非官方的 MCP 服务器，无需使用令牌，可以直接通过 API 同步 Markdown 文件与 Notion 页面或数据库。

功能

• Markdown → Notion

  • 将 H1 标题识别为页面标题
  • 创建 Notion 页面或数据库中的页面，内容基于 Markdown 内容
  • 可指定数据库 ID
  • 直接使用 Notion API（不使用令牌）

• Notion → Markdown

  • 将指定的页面或数据库页面转换为 Markdown 格式
  • 输出标题为 H1
  • 将块结构转换为 Markdown
  • 保存到文件

• MCP 服务器兼容性

  • 遵循 Model Context Protocol（MCP）
  • 提供可从 AI 工具如 Cursor 或 Cline 调用的端点
  • 基于 JSON-RPC over stdio 运行

安装

安装依赖项

# 如果尚未安装 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/Claude Code 等 AI 编码工具中使用 NotionMCP Light，需在各工具的 MCP 服务器设置 JSON 文件中添加如下配置：

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

请将 /path/to/notion-mcp-light 替换为 NotionMCP Light 的安装目录，并将 your_notion_api_token 替换为 Notion 的 API 令牌。

使用 MCP 工具

NotionMCP Light 提供了以下 MCP 工具：

uploadMarkdown

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

{
  "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

下载 Notion 页面并将其保存为 Markdown 文件。

{
  "jsonrpc": "2.0",
  "method": "downloadMarkdown",
  "params": {
    "page_id": "notion_page_id",
    "output_path": "path/to/output.md"
  },
  "id": 2
}

许可证

本项目在 MIT 许可证下发布。详情请参阅 LICENSE 文件。