NotionMCP Light

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

概述

本项目旨在解决官方 Notion Model Context Protocol (MCP) 服务器存在的效率问题（按块读写 Markdown 并消耗 LLM 令牌）。它提供无需令牌、通过 API 直接同步 Markdown 文件与 Notion 页面/数据库的非官方 MCP 服务器解决方案。

功能

• Markdown → Notion

  • 自动识别 H1 标题作为页面名称
  • 将 Markdown 内容创建为 Notion 页面或数据库条目
  • 支持指定目标数据库 ID
  • 直接调用 Notion API（零令牌消耗）

• Notion → Markdown

  • 将指定页面或数据库条目转换为 Markdown 格式
  • 页面标题输出为 H1 标题
  • 完整保留区块结构的 Markdown 转换
  • 支持本地文件保存

• MCP 服务器兼容

  • 完全遵循 Model Context Protocol（MCP）规范
  • 提供 Cursor/Cline 等 AI 工具可调用的标准化端点
  • 基于 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 配置

在 AI 工具中配置 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 替换为实际安装路径。

MCP 工具接口

支持以下标准化 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 文件。