Notion MCP 服务器

这是一个用于Notion集成的Model Context Protocol (MCP)服务器实现，提供了一个与Notion API交互的标准接口。兼容Claude Desktop和其他MCP客户端。

功能

• 列出和查询Notion数据库
• 创建和更新页面
• 在Notion工作区中搜索
• 获取数据库详情和块子项
• 使用httpx支持完整的异步/等待操作
• 使用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无法连接，请检查你的配置路径是否正确以及服务器是否在不向stdout记录的情况下运行

致谢

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