🚀 Notion MCP 服务器
Notion MCP 服务器是一个用于 Notion 集成的 Model Context Protocol (MCP) 服务器实现，它提供标准化接口，可与 Notion 的 API 进行交互。该服务器兼容 Claude Desktop 和其他 MCP 客户端，能帮助用户更便捷地使用 Notion 相关功能。
✨ 主要特性
- 可列出和查询 Notion 数据库。
- 支持创建和更新页面。
- 能在 Notion 工作区中进行搜索。
- 可获取数据库详细信息及其子块。
- 全面支持异步/等待功能（使用 httpx）。
- 使用 Pydantic v2 模型实现类型安全。
- 具有详细的日志记录的错误处理。
- 兼容 MCP 1.6.0。
📦 安装指南
- 克隆仓库：
git clone https://github.com/ccabanillas/notion-mcp.git
cd notion-mcp
- 创建虚拟环境并安装依赖项（使用 uv）：
uv venv
source .venv/bin/activate # Windows 上：.venv\Scripts\activate
uv pip install -e .
或者，使用标准 venv：
python -m venv venv
source venv/bin/activate # Windows 上：venv\Scripts\activate
pip install -e .
- 在项目根目录中创建一个
.env文件：
NOTION_API_KEY=your_notion_integration_token
💻 使用示例
基础用法
测试服务器（应正常运行且无错误）：
python -m notion_mcp
高级用法
要与 Claude Desktop 一起使用，请调整你的 claude_desktop_config.json 文件（位于 ~/Library/Application Support/Claude/claude_desktop_config.json，macOS 上）：
{
"servers": {
"notion-mcp": {
"command": "/Users/username/Projects/notion-mcp/.venv/bin/python",
"args": ["-m", "notion_mcp"],
"cwd": "/Users/username/Projects/notion-mcp"
}
}
}
请将 /Users/username/ 替换为你的实际用户目录路径。
📚 详细文档
开发
项目结构
notion-mcp/
├── src/
│ └── notion_mcp/
│ ├── models/
│ │ ├── __init__.py
│ │ └── notion.py # Pydantic 模型，用于 Notion 对象
│ ├── __init__.py
│ ├── __main__.py # 入口点
│ ├── client.py # Notion API 客户端
│ └── server.py # MCP 服务器实现
├── .env # 环境变量（在此添加你的 Notion API 密钥）
├── .gitignore
├── pyproject.toml # 项目依赖项
└── README.md
运行测试
pytest
配置
服务器需要一个 Notion 整合令牌。要设置此配置：
- 访问 https://www.notion.so/my-integrations。
- 创建一个新的整合（具有适当的读/写权限）。
- 复制生成的令牌并将其添加到
.env文件中：
NOTION_API_KEY=your_api_key_here
贡献指南
要为项目做出贡献，请遵循以下步骤：
- fork 该项目仓库。
- 创建一个新的分支用于你的功能或修复。
- 提交更改并推送分支。
- 创建一个拉取请求以合并到主要分支。
请确保在提交代码之前运行所有测试，并保持代码的高质量和文档的清晰性。
🔧 技术细节
故障排除
常见问题
- 无法安装依赖项：检查你的互联网连接，或者尝试使用不同的 Python 版本。
- 服务器启动失败：确保你已经正确配置了
.env文件中的 API 密钥，并且所有依赖项已正确安装。 - 与 Claude 不兼容：检查
claude_desktop_config.json中的路径和命令是否正确。
联系方式
如果有任何问题或反馈，请通过 GitHub Issues 提交。
📄 许可证
本项目受 MIT License 保护。