Notion MCP

🚀 Notion MCP 服務器

Notion MCP 服務器是一個用於 Notion 集成的 Model Context Protocol (MCP) 服務器實現，它提供標準化接口，可與 Notion 的 API 進行交互。該服務器兼容 Claude Desktop 和其他 MCP 客戶端，能幫助用戶更便捷地使用 Notion 相關功能。

✨ 主要特性

• 可列出和查詢 Notion 數據庫。
• 支持創建和更新頁面。
• 能在 Notion 工作區中進行搜索。
• 可獲取數據庫詳細信息及其子塊。
• 全面支持異步/等待功能（使用 httpx）。
• 使用 Pydantic v2 模型實現類型安全。
• 具有詳細的日誌記錄的錯誤處理。
• 兼容 MCP 1.6.0。

📦 安裝指南

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

💻 使用示例

基礎用法

測試服務器（應正常運行且無錯誤）：

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 整合令牌。要設置此配置：

1. 訪問 https://www.notion.so/my-integrations。
2. 創建一個新的整合（具有適當的讀/寫權限）。
3. 複製生成的令牌並將其添加到 .env 文件中：

NOTION_API_KEY=your_api_key_here

貢獻指南

要為項目做出貢獻，請遵循以下步驟：

1. fork 該項目倉庫。
2. 創建一個新的分支用於你的功能或修復。
3. 提交更改並推送分支。
4. 創建一個拉取請求以合併到主要分支。

請確保在提交代碼之前運行所有測試，並保持代碼的高質量和文檔的清晰性。

🔧 技術細節

故障排除

常見問題

• 無法安裝依賴項：檢查你的互聯網連接，或者嘗試使用不同的 Python 版本。
• 服務器啟動失敗：確保你已經正確配置了 .env 文件中的 API 密鑰，並且所有依賴項已正確安裝。
• 與 Claude 不兼容：檢查 claude_desktop_config.json 中的路徑和命令是否正確。

聯繫方式

如果有任何問題或反饋，請通過 GitHub Issues 提交。

📄 許可證

本項目受 MIT License 保護。