JinDaGe - notion-mcp MCP Details

article

README

🚀 Notion MCP 服务器

Notion MCP 服务器是一个用于 Notion 集成的 Model Context Protocol (MCP) 服务器实现，它提供标准化接口，可与 Notion 的 API 进行交互。该服务器兼容 Claude Desktop 和其他 MCP 客户端，能帮助用户更便捷地使用 Notion 相关功能。

✨ 主要特性

可列出和查询 Notion 数据库。
支持创建和更新页面。
能在 Notion 工作区中进行搜索。
可获取数据库详细信息及其子块。
全面支持异步/等待功能（使用 httpx）。
使用 Pydantic v2 模型实现类型安全。
具有详细的日志记录的错误处理。
兼容 MCP 1.6.0。

📦 安装指南

克隆仓库：

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

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

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

NOTION_API_KEY=your_notion_integration_token

💻 使用示例

基础用法

测试服务器（应正常运行且无错误）：

python -m notion_mcp

高级用法

要与 Claude Desktop 一起使用，请调整你的 claude_desktop_config.json 文件（位于 ~/Library/Application Support/Claude/claude_desktop_config.json，macOS 上）：

{
  "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 模型，用于 Notion 对象
│       ├── __init__.py        
│       ├── __main__.py        # 入口点
│       ├── client.py          # Notion API 客户端
│       └── server.py          # MCP 服务器实现
├── .env                       # 环境变量（在此添加你的 Notion API 密钥）
├── .gitignore
├── pyproject.toml             # 项目依赖项
└── README.md

运行测试

pytest

配置

服务器需要一个 Notion 整合令牌。要设置此配置：

访问 https://www.notion.so/my-integrations。
创建一个新的整合（具有适当的读/写权限）。
复制生成的令牌并将其添加到 .env 文件中：

NOTION_API_KEY=your_api_key_here

贡献指南

要为项目做出贡献，请遵循以下步骤：

fork 该项目仓库。
创建一个新的分支用于你的功能或修复。
提交更改并推送分支。
创建一个拉取请求以合并到主要分支。

请确保在提交代码之前运行所有测试，并保持代码的高质量和文档的清晰性。

🔧 技术细节

故障排除

常见问题

无法安装依赖项：检查你的互联网连接，或者尝试使用不同的 Python 版本。
服务器启动失败：确保你已经正确配置了 .env 文件中的 API 密钥，并且所有依赖项已正确安装。
与 Claude 不兼容：检查 claude_desktop_config.json 中的路径和命令是否正确。

联系方式

如果有任何问题或反馈，请通过 GitHub Issues 提交。

📄 许可证

本项目受 MIT License 保护。

notion-mcp