MCP通知上传服务器
用于Notion文件上传API的模型上下文协议（MCP）服务器。
功能
📁 上载默认文件
- 通过Notion API上传文件（最大20MB）
- 返回上载的文件URL
- 支持自定义文件名
🚀 完整的工作流（NEW！）
- 一键式解决方案：一次上传文件+附加页面+下载URL
- 自动将文件附加到指定的Notion页面
- 立即返回可用的下载URL
- 提供文件元数据和过期时间信息
安装
# uv를 사용하는 경우 (권장)
uv sync
# pip를 사용하는 경우
pip install -e .
# 또는 직접 의존성 설치
pip install httpx mcp[cli]Claude桌面设置
1.配置文件位置
macOS：
~/Library/Application Support/Claude/claude_desktop_config.json窗户：
%APPDATA%\Claude\claude_desktop_config.json2.默认设置（使用uv）
{
"mcpServers": {
"notion-upload": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp_notion_upload",
"run",
"mcp_notion_upload.py"
]
}
}
}3.设置直接运行Python
{
"mcpServers": {
"notion-upload": {
"command": "python",
"args": [
"/path/to/mcp_notion_upload.py"
]
}
}
}4.启用虚拟环境
{
"mcpServers": {
"notion-upload": {
"command": "/path/to/.venv/bin/python",
"args": [
"/path/to/mcp_notion_upload.py"
]
}
}
}5.将令牌设置为环境变量（建议安全）
如果将令牌预置为环境变量，则无需每次输入：
{
"mcpServers": {
"notion-upload": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp_notion_upload",
"run",
"mcp_notion_upload.py"
],
"env": {
"NOTION_API_TOKEN": "secret_your_notion_token_here"
}
}
}
}使用方法
在Claude Desktop中设置后，您可以使用：
🚀 完整的工作流（推荐）
只需一次请求，从上传到下载URL！
사용자: "문서.pdf 파일을 페이지 ID 2785bbc0e5c281f48dfae9a48f53f6a6에 첨부해서 다운로드 URL 받아줘"
Claude: [파일 업로드 + 페이지 첨부 + 다운로드 URL 반환]返回的信息：
- 📁 文件上载ID
- 🔗 文件块ID
- 🌐 下载URL（有效1小时）
- 过期时间
- 📊 文件元数据
📁 上载默认文件
如果只需要简单上载：
사용자: "/Users/me/doc.pdf를 업로드해줘"
Claude: [파일 업로드 후 업로드 ID 반환]参数传递方法
MCP服务器的参数在与Claude对话时以自然语言传递：
- 完整的工作流示例
"report.pdf를 페이지 2785bbc0e5c281f48dfae9a48f53f6a6에 첨부하고 다운로드 URL 가져와줘"
"image.png를 회사로고.png 이름으로 페이지 abc123def456에 첨부해줘"
"토큰 secret_xxx 사용해서 문서.pdf를 페이지 xyz789에 업로드하고 URL 받아줘"- 默认上载示例
"Notion 토큰 secret_abcd1234를 사용해서 /Users/me/doc.pdf를 업로드해줘"
"파일 /path/to/image.png를 logo.png라는 이름으로 Notion에 업로드해줘"- 使用环境变量（如果已预置令牌）
사용자: "문서.pdf를 페이지 abc123에 첨부해서 다운로드 링크 받아줘"
Claude: [환경 변수의 토큰을 사용하여 완전한 워크플로우 수행]所需信息
🚀 对于完整工作流
- Notion API令牌：Notion Integration生成的令牌（必需）
- 文件路径：要上载的文件的完整路径（必需）
- 页面ID：要附加文件的Notion页面的ID（必需）
- 文件名：自定义文件名（可选）
- 标题：文件块的标题（可选）
📁 对于默认上载
- Notion API令牌：Notion Integration生成的令牌（必需）
- 文件路径：要上载的文件的完整路径（必需）
- 文件名：自定义文件名（可选，使用未指定的源文件名）
如何查找Notion页面ID
可以从Notion页面URL提取ID：
https://www.notion.so/workspace/Page-Title-2785bbc0e5c281f48dfae9a48f53f6a6
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
이 부분이 페이지 ID입니다包含或排除破折号（-）的形状都可用：
2785bbc0-e5c2-81f4-8dfa-e9a48f53f6a6✅2785bbc0e5c281f48dfae9a48f53f6a6✅
如何发放Notion API令牌
- 概念开发者连接到
- 单击“New integration”
- 设置和创建集成名称
- 复制“Internal Integration Token”
API函数列表
此MCP服务器提供两种工具：
1. upload_file_to_notion （默认上载）
只上载文件并返回文件ID。
返回值： 上传的文件URL（string）
2. upload_and_attach_file_to_page （完整的工作流程）
一次处理文件上传+页面附件+下载URL。
返回值： 结构化对象（dict）
{
"file_upload_id": "2785bbc0-e5c2-81f6-932c-00b265c6d205",
"file_block_id": "2785bbc0-e5c2-816e-b837-ec0b4298bf29",
"download_url": "https://prod-files-secure.s3.us-west-2.amazonaws.com/...",
"expiry_time": "2025-09-24T23:47:33.485Z",
"filename": "document.pdf",
"content_type": "application/pdf",
"file_size": 51290,
"status": "success",
"message": "File 'document.pdf' uploaded and attached successfully"
}注意事项
- 最大文件大小：20MB
- 支持的文件格式：图像、PDF、音频、视频等
- 完整工作流：下载URL将在1小时后过期（新URL可通过页面复查更新）
- 默认上载：上传的文件需要在1小时内手动附加到Notion页面或块
- 更改设置后需要重新启动Claude Desktop
- 附加页面时需要该页面的编辑权限
故障射击
- 如果服务器无法运行
- 验证路径是否为绝对路径 - 验证Python/uv可执行文件路径是否正确 - 验证是否已安装所需的软件包
- 文件上载失败
- 验证Notion API令牌是否有效 - 验证文件大小是否小于20MB - 验证文件是否真实存在
- 附加页面失败（完整工作流）
- 验证页面ID是否正确（不包括破折号/不包括破折号） - 验证Integration是否具有访问该页面的权限 - 验证页面是否已删除
- 权限相关错误
- 验证是否已邀请Notion Integration进入页面 - 在页面共享设置中，验证对Integration的编辑权限
版本历史记录
v2.0.0（最新）
- ✅ 完整工作流 添加：
upload_and_attach_file_to_page - 通过一次呼叫获得文件上传+页面附件+下载URL
- 通过结构化响应提供文件元数据
- 改进的错误处理和调试信息
v1.0.0
- 基本文件上传功能：
upload_file_to_notion - 实现模型上下文协议（MCP）服务器
- 支持与Claude Desktop集成