README.md•3.21 kB
# Notion MCP Server
這是一個 Model Context Protocol (MCP) 伺服器，用於連接和操作 Notion API。它提供了一套完整的工具來讀取、寫入和管理 Notion 頁面與資料庫。
## 功能特色
- 🔍 **搜尋頁面** - 在 Notion 工作區中搜尋頁面
- 📄 **頁面操作** - 取得、建立和更新 Notion 頁面
- 🗃️ **資料庫查詢** - 查詢和操作 Notion 資料庫
- 📋 **內容管理** - 讀取和修改頁面內容區塊
- 🔄 **即時同步** - 透過 MCP 協議即時與 Notion 同步
## 安裝和設定
### 1. 安裝依賴
```bash
npm install
```
### 2. 設定 Notion 整合
1. 前往 [Notion 整合設定頁面](https://www.notion.so/my-integrations)
2. 建立新的整合
3. 複製整合 token
4. 建立 `.env` 檔案並加入您的 token：
```bash
cp .env.example .env
# 編輯 .env 檔案，加入您的 Notion token
```
### 3. 建立專案
```bash
npm run build
```
## 使用方法
### 開發模式
```bash
npm run dev
```
### 生產模式
```bash
npm start
```
### 監控模式（自動重新載入）
```bash
npm run watch
```
## 可用的工具
### 頁面操作
- `get-page` - 根據 ID 取得頁面詳細資訊
- `search-pages` - 搜尋頁面
- `create-page` - 建立新頁面
- `update-page` - 更新頁面屬性
### 資料庫操作
- `query-database` - 查詢資料庫內容
### 資源
- `notion://recent-pages` - 最近存取的頁面
- `notion://databases` - 可存取的資料庫清單
## 在 VS Code 中使用
1. 確保已安裝 MCP 相關的 VS Code 擴充功能
2. 使用 `.vscode/mcp.json` 配置檔案來設定伺服器連接
3. 在 VS Code 中啟動偵錯模式以測試 MCP 伺服器
## API 範例
### 搜尋頁面
```json
{
"name": "search-pages",
"arguments": {
"query": "meeting notes",
"filter": {
"property": "Status",
"value": "Active"
}
}
}
```
### 建立頁面
```json
{
"name": "create-page",
"arguments": {
"parent": {
"database_id": "your-database-id"
},
"properties": {
"Name": {
"title": [
{
"text": {
"content": "新頁面標題"
}
}
]
}
}
}
}
```
## 錯誤排除
### 常見問題
1. **Authentication Error**: 確認 `NOTION_TOKEN` 環境變數已正確設定
2. **Permission Error**: 確認 Notion 整合有適當的權限存取所需的頁面和資料庫
3. **Module Resolution Error**: 確認所有依賴已正確安裝
### 偵錯
在開發模式下，伺服器會在 stderr 輸出詳細的偵錯資訊。
## 專案結構
```
.
├── src/
│ ├── index.ts # MCP 伺服器主程式
│ └── notion-service.ts # Notion API 服務類別
├── .vscode/
│ └── mcp.json # VS Code MCP 配置
├── .github/
│ └── copilot-instructions.md # GitHub Copilot 指令
├── package.json
├── tsconfig.json
├── .env.example
└── README.md
```
## 授權
MIT License
## 相關連結
- [Model Context Protocol 官方文件](https://modelcontextprotocol.io/)
- [Notion API 文件](https://developers.notion.com/)
- [MCP SDK](https://github.com/modelcontextprotocol/sdk)