Notion MCP 服务器

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

特性

• 列出和查询 Notion 数据库
• 创建和更新页面
• 在整个 Notion 工作区中搜索
• 获取数据库详情和块子项
• 使用 httpx 支持完整的异步/等待
• 使用 Pydantic v2 模型保证类型安全
• 详细的错误处理和日志记录
• 兼容 MCP 1.6.0

安装

1. 克隆仓库：

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

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

1. 在项目根目录创建一个 .env 文件：

NOTION_API_KEY=your_notion_integration_token

使用

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

python -m notion_mcp

1. 若要与 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

1. 通过数据库的“分享”菜单将您的 Notion 数据库共享给该集成

贡献

1. 叉取仓库
2. 创建你的特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个拉取请求

许可证

MIT 许可证 - 自行承担风险使用

故障排除

常见问题

• 连接错误：确保您的 Notion API 密钥正确且您有互联网访问权限
• 权限错误：确保您的集成已被授予访问您尝试访问的数据的权限
• Claude Desktop 集成：如果 Claude Desktop 无法连接，请检查配置路径是否正确，并且服务器正在运行且没有向 stdout 记录日志

致谢

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