Markdown 2通知
用于将Markdown文件上传到Notion的模型上下文协议(MCP)服务器。此工具允许您轻松地将Markdown文档转换为Notion页面,同时保留格式和结构。
🚀 特性
- ✅ 将Markdown文件转换为Notion页面 -无缝转换.md文件
- ✅ 自动处理大文件 -具有100多个块的文件会自动拆分
- ✅ 基于URL的页面定位 -只需提供一个Notion页面URL作为父级
- ✅ 支持常见的Markdown元素 -标题、列表、代码块、链接等。
- ✅ 数据库和页面支持 -上传到数据库或作为子页面
- ✅ 基于FastMCP框架构建 -易于与MCP客户端集成
📦 安装
- 克隆存储库:```bash
git clone https://github.com/bonbonsan/markdown2notion.git
cd markdown2notion
2. **安装依赖项:**```bash
pip install -r requirements.txt
# or using pyproject.toml
pip install -e .
- 设置您的Notion API令牌:```bash
Create .env file
echo "NOTION_TOKEN=your_notion_api_token_here" > .env
**获取您的Notion API令牌:**
1. 首选 https://www.notion.so/my-integrations
1. 创建新的集成
1. 复制内部集成令牌
1. **重要提示:** 授予对目标页面/数据库的集成访问权限
## 🔧 用法
### 作为MCP服务器(推荐)
#### Cline(VS代码扩展)
1. **设置虚拟环境并安装依赖项:**```bash
cd markdown2notion
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
-
打开命令选项板→
Cline: Open MCP Settings. -
添加或更新
cline_mcp_settings.json与:```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. **设置虚拟环境并安装依赖项:**```bash
cd markdown2notion
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
- 创建工作区设置 在您的项目中:
创建.vscode/settings.json在项目根目录中使用:```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. **设置虚拟环境并安装依赖项:**```bash
cd markdown2notion
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
-
在Claude Desktop中,单击 克劳德→ 设置→ 开发者→ 打开配置文件.
-
将以下条目添加到
claude_desktop_config.json(macOS)或您平台上的等效配置文件:```json
{
"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检查路径**:确认在配置文件中使用了绝对路径
1. **安装相关性**: `pip install -r requirements.txt`确认在虚拟环境中运行
1. **重新启动应用程序**: VS Code(CLINE使用时)或Claude Desktop完全重新启动
1. **验证路径**:验证配置文件中的路径是否与实际文件位置匹配
### Python直接运行脚本
MCP如果服务器无法正常工作,请选择Python您可以直接运行脚本:```bash
# 仮想環境をアクティベート
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}')
"
直接使用
您也可以直接使用这些组件:```python
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扩展)示例```text
このMarkdownファイルをNotionにアップロードしてください:
/Users/username/Documents/my-notes.md
親ページURLはこちらです:
https://www.notion.so/16132a3709e4816cb512e4d73d345003
CLINE自动upload_markdown调用该工具并显示以下结果:```text
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)使用示例```text
以下のMarkdownコンテンツを「週報 2024年10月」というタイトルでNotionページに変換してください:
# 今週の進捗
- プロジェクトAの設計完了
- バグ修正3件対応
## 来週の予定
- 実装開始
- コードレビュー
親ページ: https://www.notion.so/work-reports-abc123def456
Claude Code的upload_markdown_content使用工具做出以下响应:```text
Successfully uploaded content as '週報 2024年10月' to Notion.
Page ID: 12345678-90ab-cdef-1234-567890abcdef
View at: https://www.notion.so/12345678090abcdef1234567890abcdef
### 数据库指定中的使用示例```text
この研究ノートをNotionのデータベースにアップロードしてください:
- ファイル: /Users/username/research/ml-paper-summary.md
- データベースID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
- タイトルはファイル名を使用
多文件批量上载示例```text
以下の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个块创建初始页面
1. 剩余的块会自动以块的形式附加
1. 结果:一个完整的Notion页面,包含所有内容
## 📋 需求
- Python 3.8+
- 概念客户端
- fastmcp
- python dotenv
- mistune(用于Markdown解析)
## 🗂 项目结构```bash
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
