Notion MCP 服务器

一个为 Notion 集成实现的模型上下文协议（MCP）服务器，提供与 Notion API 交互的标准化接口。兼容 Claude Desktop 及其他 MCP 客户端。

功能特性

• 列出并查询 Notion 数据库
• 创建和更新页面
• 跨 Notion 工作区搜索
• 获取数据库详情和区块子项
• 完整支持 httpx 的 async/await 异步操作
• 使用 Pydantic v2 模型实现类型安全
• 详细的错误处理与日志记录
• 兼容 MCP 1.6.0 协议

安装指南

1. 克隆代码库：

git clone https://github.com/ccabanillas/notion-mcp.git
cd notion-mcp

2. 创建虚拟环境并安装依赖（使用 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 .

3. 在项目根目录创建 .env 文件：

NOTION_API_KEY=你的Notion集成令牌

使用说明

1. 测试服务器（应无报错运行）：

python -m notion_mcp

2. 与 Claude Desktop 配合使用时，修改 claude_desktop_config.json 配置文件（macOS 路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "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      # Notion 对象的 Pydantic 模型
│       ├── __init__.py        
│       ├── __main__.py        # 程序入口
│       ├── client.py          # Notion API 客户端
│       └── server.py          # MCP 服务器实现
├── .env                       # 环境变量文件（需添加 Notion API 密钥）
├── .gitignore
├── pyproject.toml             # 项目依赖配置
└── README.md

运行测试

pytest

配置说明

服务器需要 Notion 集成令牌，配置步骤：

1. 访问 https://www.notion.so/my-integrations
2. 创建具有适当权限的新集成（按需设置读写权限）
3. 复制集成令牌
4. 将其添加到项目根目录的 .env 文件中：

NOTION_API_KEY=你的Notion集成令牌

5. 通过数据库的"Share"菜单将 Notion 数据库共享给该集成

贡献指南

1. Fork 本代码库
2. 创建特性分支（git checkout -b feature/amazing-feature）
3. 提交修改（git commit -m '添加新特性'）
4. 推送分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

开源许可

MIT 许可协议 - 使用风险自担

故障排除

常见问题

• 连接错误：检查 Notion API 密钥是否正确，并确认网络连接正常
• 权限错误：确保集成已获得目标数据库的访问权限
• Claude Desktop 集成问题：若连接失败，请检查配置文件路径是否正确，并确认服务器运行时未向 stdout 输出日志

致谢

• 专为 Claude Desktop 及其他 MCP 客户端构建
• 基于 Notion API（最新兼容版本 2022-02-22）
• 保持 MCP 1.6.0 协议兼容性
• 特别感谢 danhilse 的 notion-mcp-server 项目提供参考