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 集成服务器：

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  # 在 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=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      # 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=your_notion_integration_token

5. 将您的 Notion 数据库与集成共享（从数据库的“共享”菜单中）

贡献

1. 分叉仓库
2. 创建您的功能分支（git checkout -b feature/amazing-feature）
3. 提交您的更改（git commit -m '添加一些很棒的功能'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开一个拉取请求

许可证

MIT 许可证 - 使用风险自负

故障排除

常见问题

• 连接错误：确保您的 Notion API 密钥正确且您有互联网访问权限
• 权限错误：确保您的集成已被授予访问您尝试访问的数据库的权限
• Claude Desktop 集成：如果 Claude Desktop 无法连接，请检查您的配置路径是否正确以及服务器是否在没有日志输出到标准输出的情况下运行

致谢

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