markdown2notion

Markdown 2通知

用于将Markdown文件上传到Notion的模型上下文协议（MCP）服务器。此工具允许您轻松地将Markdown文档转换为Notion页面，同时保留格式和结构。

🚀 特性

• ✅ 将Markdown文件转换为Notion页面 -无缝转换.md文件
• ✅ 自动处理大文件 -具有100多个块的文件会自动拆分
• ✅ 基于URL的页面定位 -只需提供一个Notion页面URL作为父级
• ✅ 支持常见的Markdown元素 -标题、列表、代码块、链接等。
• ✅ 数据库和页面支持 -上传到数据库或作为子页面
• ✅ 基于FastMCP框架构建 -易于与MCP客户端集成

📦 安装

1. 克隆存储库：

git clone https://github.com/bonbonsan/markdown2notion.git
cd markdown2notion

1. 安装依赖项：

pip install -r requirements.txt
# or using pyproject.toml
pip install -e .

1. 设置您的Notion API令牌：

# Create .env file
echo "NOTION_TOKEN=your_notion_api_token_here" > .env

获取您的Notion API令牌：

1. 首选 https://www.notion.so/my-integrations
2. 创建新的集成
3. 复制内部集成令牌
4. 重要提示： 授予对目标页面/数据库的集成访问权限

🔧 用法

作为MCP服务器（推荐）

Cline（VS代码扩展）

1. 设置虚拟环境并安装依赖项：

   cd markdown2notion
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt

1. 打开命令选项板→ Cline: Open MCP Settings.

1. 添加或更新 cline_mcp_settings.json 与：

   {
     "mcpServers": {
       "markdown2notion": {
         "command": "/absolute/path/to/markdown2notion/.venv/bin/python",
         "args": ["/absolute/path/to/markdown2notion/src/server.py"]
       }
     }
   }

⚠️ 重要提示：

- 使用 绝对路径 对两者 command 和 args - 点 command 到虚拟环境的Python解释器 - 替换 /absolute/path/to/markdown2notion 使用您的实际项目路径 - macOS/Linux示例： /Users/username/Documents/markdown2notion/.venv/bin/python - Windows示例： C:\Users\username\Documents\markdown2notion\.venv\Scripts\python.exe

1. 重新启动VS代码 （不仅仅是Cline）保存配置文件后。

克劳德代码（VS代码扩展）

1. 设置虚拟环境并安装依赖项：

   cd markdown2notion
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt

1. 创建工作区设置 在您的项目中：

创建 .vscode/settings.json 在项目根目录中使用：

   {
     "claude.mcpServers": {
       "markdown2notion": {
         "command": "/absolute/path/to/markdown2notion/.venv/bin/python",
         "args": ["/absolute/path/to/markdown2notion/src/server.py"],
         "enabled": true
       }
     }
   }

⚠️ 重要提示：

- 使用 绝对路径 对两者 command 和 args - 点 command 到虚拟环境的Python解释器 - 替换 /absolute/path/to/markdown2notion 使用您的实际项目路径 - macOS/Linux示例： /Users/username/Documents/markdown2notion/.venv/bin/python - Windows示例： C:\Users\username\Documents\markdown2notion\.venv\Scripts\python.exe

克劳德桌面（独立应用程序）

1. 设置虚拟环境并安装依赖项：

   cd markdown2notion
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt

1. 在Claude Desktop中，单击 克劳德→ 设置→ 开发者→ 打开配置文件.

1. 将以下条目添加到 claude_desktop_config.json （macOS）或您平台上的等效配置文件：

   {
     "mcpServers": {
       "markdown2notion": {
         "command": "/absolute/path/to/markdown2notion/.venv/bin/python",
         "args": ["/absolute/path/to/markdown2notion/src/server.py"],
         "enabled": true
       }
     }
   }

⚠️ 重要提示：

- 使用 绝对路径 对两者 command 和 args - 点 command 到虚拟环境的Python解释器 - 替换 /absolute/path/to/markdown2notion 使用您的实际项目路径 - macOS/Linux示例： /Users/username/Documents/markdown2notion/.venv/bin/python - Windows示例： C:\Users\username\Documents\markdown2notion\.venv\Scripts\python.exe

1. 重新启动克劳德桌面 保存配置文件后。

注： 当服务器从此存储库运行时，它会读取 NOTION_TOKEN 来自您当地的 .env 文件。确保您已创建 .env 使用Notion API令牌文件，如安装部分所述。

🔍 故障排除

MCP服务器连接问题

如果CLINE啊Claude Desktop中显示“MCP服务器未连接”错误时：

1. 虚拟化Python检查路径：确认在配置文件中使用了绝对路径
2. 安装相关性: pip install -r requirements.txt确认在虚拟环境中运行
3. 重新启动应用程序: VS Code（CLINE使用时）或Claude Desktop完全重新启动
4. 验证路径：验证配置文件中的路径是否与实际文件位置匹配

Python直接运行脚本

MCP如果服务器无法正常工作，请选择Python您可以直接运行脚本：

# 仮想環境をアクティベート
source .venv/bin/activate  # macOS/Linux
# または
.venv\Scripts\activate  # Windows

# スクリプトを実行
python -c "
from src.notion_uploader import NotionUploader
uploader = NotionUploader()
page_id = uploader.upload_markdown_file(
    filepath='/path/to/your/file.md',
    parent_url='https://www.notion.so/your-parent-page-url'
)
print(f'Uploaded! Page ID: {page_id}')
"

直接使用

您也可以直接使用这些组件：

from src.notion_uploader import NotionUploader

uploader = NotionUploader()

# Using URL (recommended)
page_id = uploader.upload_markdown_file(
    filepath="path/to/your/document.md",
    parent_url="https://www.notion.so/your-page-url-here"
)

# Using page ID directly
page_id = uploader.upload_markdown_file(
    filepath="path/to/your/document.md",
    parent_page_id="16132a37-09e4-816c-b512-e4d73d345003"
)

🛠 可用的MCP工具

当用作MCP服务器时，可以使用以下工具：

upload_markdown

将Markdown文件上传到Notion：

• filepath：.md文件的路径（必需）
• parent_url：通知页面URL（例如。， https://notion.so/page-title-abc123...)
• database_id：目标数据库ID（替代parent_url）
• parent_page_id：父页面ID（替代Parent_url）

upload_markdown_content

直接上传Markdown内容：

• content：您的降价内容为文本（必填）
• title：页面标题（必填）
• parent_url：通知页面URL（推荐）
• database_id 或 parent_page_id：替代目标规范

list_database_pages

列出数据库中的现有页面以供参考。

get_database_info

获取有关特定数据库的信息。

💬 提示执行示例

MCP如果服务器设置成功，请在以下提示下Markdown打开文件Notion中所述修改相应参数的值。

CLINE（VS Code扩展）示例

このMarkdownファイルをNotionにアップロードしてください:
/Users/username/Documents/my-notes.md

親ページURLはこちらです:
https://www.notion.so/16132a3709e4816cb512e4d73d345003

CLINE自动upload_markdown调用该工具并显示以下结果：

Successfully uploaded 'my-notes.md' to Notion.
Page ID: 29932a37-09e4-819d-a790-e8c025f28af5
View at: https://www.notion.so/29932a3709e4819da790e8c025f28af5

Claude Code（Claude Desktop）使用示例

以下のMarkdownコンテンツを「週報 2024年10月」というタイトルでNotionページに変換してください：

# 今週の進捗
- プロジェクトAの設計完了
- バグ修正3件対応

## 来週の予定
- 実装開始
- コードレビュー

親ページ: https://www.notion.so/work-reports-abc123def456

Claude Code的upload_markdown_content使用工具做出以下响应：

Successfully uploaded content as '週報 2024年10月' to Notion.
Page ID: 12345678-90ab-cdef-1234-567890abcdef
View at: https://www.notion.so/12345678090abcdef1234567890abcdef

数据库指定中的使用示例

この研究ノートをNotionのデータベースにアップロードしてください：
- ファイル: /Users/username/research/ml-paper-summary.md
- データベースID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
- タイトルはファイル名を使用

多文件批量上载示例

以下のMarkdownファイルをすべて同じ親ページにアップロードしてください：
1. /path/to/chapter1.md
2. /path/to/chapter2.md  
3. /path/to/chapter3.md

親ページ: https://www.notion.so/book-draft-xyz789

注意: MCP如果服务器未连接CLINE自动的Python回退到直接执行脚本。

📖 示例

直接上传Markdown内容：

• content：您的降价内容为文本（必填）
• title：页面标题（必填）
• parent_url：通知页面URL（推荐）
• database_id 或 parent_page_id：替代目标规范

注意: MCP如果服务器未连接CLINE自动的Python回退到直接执行脚本。

📝 支持的Markdown元素

• 标头 （H1-H6）→ 概念标题块
• 段落 → 概念段落块
• 列表 （项目符号和编号）→ 概念列表块
• 代码块 → 概念代码块
• 内联代码 → Notion内联代码
• 粗体和斜体文本 → 富文本格式概念
• 链接 → 概念链接

🔄 大文件处理

具有100个以上块的文件将自动处理：

1. 前100个块创建初始页面
2. 剩余的块会自动以块的形式附加
3. 结果：一个完整的Notion页面，包含所有内容

📋 需求

• Python 3.8+
• 概念客户端
• fastmcp
• python dotenv
• mistune（用于Markdown解析）

🗂 项目结构

markdown2notion/
├── src/
│   ├── server.py           # MCP server implementation
│   ├── notion_uploader.py  # Core Notion API client
│   ├── markdown_processor.py # Markdown to Notion blocks converter
│   └── __init__.py
├── docs/
│   ├── design.md          # Architecture documentation
│   └── api/               # Detailed API docs
├── tests/
│   ├── test_notion_uploader.py
│   ├── test_markdown_processor.py
│   └── test_server.py
├── .env.example          # Environment template
├── pyproject.toml        # Project configuration
└── README.md            # This file