Notion MCP Server

Notion MCP 服务

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

功能

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

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Notion Integration Server：

npx -y @smithery/cli install @ccabanillas/notion-mcp --client claude

手动安装

1. 克隆代码库：

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

2. 创建虚拟环境并安装依赖（使用 uv）：

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

或者，使用标准 venv：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

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

NOTION_API_KEY=your_notion_integration_token

使用方法

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      # Pydantic models for Notion objects
│       ├── __init__.py        
│       ├── __main__.py        # Entry point
│       ├── client.py          # Notion API client
│       └── server.py          # MCP server implementation
├── .env                       # Environment variables (add your Notion API key here)
├── .gitignore
├── pyproject.toml             # Project dependencies
└── README.md

运行测试

pytest

配置

此服务需要 Notion 集成令牌。设置步骤如下：

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

NOTION_API_KEY=your_notion_integration_token

5. 将 Notion 数据库共享给该集成（通过数据库的“Share”菜单）

参与贡献

1. Fork 代码库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

MIT 许可证——使用风险自负

故障排除

常见问题

• 连接错误：请确保 Notion API 密钥正确，且可以访问互联网
• 权限错误：请确保已授予集成访问你要访问的数据库的权限
• Claude Desktop 集成：如果 Claude Desktop 无法连接，请检查配置路径是否正确，以及服务运行时是否未向 stdout 输出日志

致谢

• 为兼容 Claude Desktop 和其他 MCP 客户端而构建
• 使用 Notion API（最新兼容版本为 2022-02-22）
• 持续保持与 MCP 1.6.0 的兼容性
• 特别感谢 danhilse，我参考了他的 notion-mcp-server 项目