README.md•7.83 kB
# MCP Notion Upload Server
Notion 파일 업로드 API를 위한 MCP (Model Context Protocol) 서버입니다.
## 기능
### 📁 기본 파일 업로드
- Notion API를 통한 파일 업로드 (최대 20MB)
- 업로드된 파일 URL 반환
- 커스텀 파일명 지원
### 🚀 완전한 워크플로우 (NEW!)
- **원클릭 솔루션**: 파일 업로드 + 페이지 첨부 + 다운로드 URL을 한 번에
- 지정된 Notion 페이지에 자동으로 파일 첨부
- 즉시 사용 가능한 다운로드 URL 반환
- 파일 메타데이터와 만료 시간 정보 제공
## 설치
```bash
# uv를 사용하는 경우 (권장)
uv sync
# pip를 사용하는 경우
pip install -e .
# 또는 직접 의존성 설치
pip install httpx mcp[cli]
```
## Claude Desktop 설정
### 1. 설정 파일 위치
macOS:
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
Windows:
```
%APPDATA%\Claude\claude_desktop_config.json
```
### 2. 기본 설정 (uv 사용)
```json
{
"mcpServers": {
"notion-upload": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp_notion_upload",
"run",
"mcp_notion_upload.py"
]
}
}
}
```
### 3. Python 직접 실행 설정
```json
{
"mcpServers": {
"notion-upload": {
"command": "python",
"args": [
"/path/to/mcp_notion_upload.py"
]
}
}
}
```
### 4. 가상환경 사용 설정
```json
{
"mcpServers": {
"notion-upload": {
"command": "/path/to/.venv/bin/python",
"args": [
"/path/to/mcp_notion_upload.py"
]
}
}
}
```
### 5. 환경 변수로 토큰 설정 (보안 권장)
토큰을 환경 변수로 미리 설정하면 매번 입력하지 않아도 됩니다:
```json
{
"mcpServers": {
"notion-upload": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp_notion_upload",
"run",
"mcp_notion_upload.py"
],
"env": {
"NOTION_API_TOKEN": "secret_your_notion_token_here"
}
}
}
}
```
## 사용 방법
Claude Desktop에서 설정 후, 다음과 같이 사용할 수 있습니다:
### 🚀 완전한 워크플로우 (추천)
**한 번의 요청으로 업로드부터 다운로드 URL까지!**
```
사용자: "문서.pdf 파일을 페이지 ID 2785bbc0e5c281f48dfae9a48f53f6a6에 첨부해서 다운로드 URL 받아줘"
Claude: [파일 업로드 + 페이지 첨부 + 다운로드 URL 반환]
```
**반환되는 정보:**
- 📁 파일 업로드 ID
- 🔗 파일 블록 ID
- 🌐 다운로드 URL (1시간 유효)
- ⏰ 만료 시간
- 📊 파일 메타데이터
### 📁 기본 파일 업로드
**단순 업로드만 필요한 경우:**
```
사용자: "/Users/me/doc.pdf를 업로드해줘"
Claude: [파일 업로드 후 업로드 ID 반환]
```
### 파라미터 전달 방법
MCP 서버의 파라미터들은 Claude와의 대화 중에 자연어로 전달합니다:
1. **완전한 워크플로우 예시**
```
"report.pdf를 페이지 2785bbc0e5c281f48dfae9a48f53f6a6에 첨부하고 다운로드 URL 가져와줘"
"image.png를 회사로고.png 이름으로 페이지 abc123def456에 첨부해줘"
"토큰 secret_xxx 사용해서 문서.pdf를 페이지 xyz789에 업로드하고 URL 받아줘"
```
2. **기본 업로드 예시**
```
"Notion 토큰 secret_abcd1234를 사용해서 /Users/me/doc.pdf를 업로드해줘"
"파일 /path/to/image.png를 logo.png라는 이름으로 Notion에 업로드해줘"
```
3. **환경 변수 사용시 (토큰이 미리 설정된 경우)**
```
사용자: "문서.pdf를 페이지 abc123에 첨부해서 다운로드 링크 받아줘"
Claude: [환경 변수의 토큰을 사용하여 완전한 워크플로우 수행]
```
### 필요한 정보
#### 🚀 완전한 워크플로우의 경우
1. **Notion API 토큰**: Notion Integration에서 생성한 토큰 (필수)
2. **파일 경로**: 업로드할 파일의 전체 경로 (필수)
3. **페이지 ID**: 파일을 첨부할 Notion 페이지의 ID (필수)
4. **파일명**: 커스텀 파일명 (선택사항)
5. **캡션**: 파일 블록의 캡션 (선택사항)
#### 📁 기본 업로드의 경우
1. **Notion API 토큰**: Notion Integration에서 생성한 토큰 (필수)
2. **파일 경로**: 업로드할 파일의 전체 경로 (필수)
3. **파일명**: 커스텀 파일명 (선택사항, 미지정시 원본 파일명 사용)
### Notion 페이지 ID 찾는 방법
Notion 페이지 URL에서 ID를 추출할 수 있습니다:
```
https://www.notion.so/workspace/Page-Title-2785bbc0e5c281f48dfae9a48f53f6a6
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
이 부분이 페이지 ID입니다
```
대시(-) 포함 또는 제외된 형태 모두 사용 가능:
- `2785bbc0-e5c2-81f4-8dfa-e9a48f53f6a6` ✅
- `2785bbc0e5c281f48dfae9a48f53f6a6` ✅
### Notion API 토큰 발급 방법
1. [Notion Developers](https://www.notion.so/my-integrations)에 접속
2. "New integration" 클릭
3. Integration 이름 설정 및 생성
4. "Internal Integration Token" 복사
## API 함수 목록
이 MCP 서버는 두 가지 도구를 제공합니다:
### 1. `upload_file_to_notion` (기본 업로드)
파일만 업로드하고 파일 ID를 반환합니다.
**반환값:** 업로드된 파일 URL (string)
### 2. `upload_and_attach_file_to_page` (완전한 워크플로우) ⭐
파일 업로드 + 페이지 첨부 + 다운로드 URL을 한 번에 처리합니다.
**반환값:** 구조화된 객체 (dict)
```json
{
"file_upload_id": "2785bbc0-e5c2-81f6-932c-00b265c6d205",
"file_block_id": "2785bbc0-e5c2-816e-b837-ec0b4298bf29",
"download_url": "https://prod-files-secure.s3.us-west-2.amazonaws.com/...",
"expiry_time": "2025-09-24T23:47:33.485Z",
"filename": "document.pdf",
"content_type": "application/pdf",
"file_size": 51290,
"status": "success",
"message": "File 'document.pdf' uploaded and attached successfully"
}
```
## 주의사항
- 최대 파일 크기: 20MB
- 지원 파일 형식: 이미지, PDF, 오디오, 비디오 등
- **완전한 워크플로우**: 다운로드 URL은 1시간 후 만료 (새 URL은 페이지 재조회로 갱신 가능)
- **기본 업로드**: 업로드된 파일은 1시간 이내에 Notion 페이지나 블록에 수동 첨부 필요
- 설정 변경 후 Claude Desktop 재시작 필요
- 페이지 첨부 시 해당 페이지에 대한 편집 권한 필요
## 트러블슈팅
1. **서버가 실행되지 않는 경우**
- 경로가 절대 경로인지 확인
- Python/uv 실행 파일 경로가 정확한지 확인
- 필요한 패키지가 설치되었는지 확인
2. **파일 업로드 실패**
- Notion API 토큰이 유효한지 확인
- 파일 크기가 20MB 이하인지 확인
- 파일이 실제로 존재하는지 확인
3. **페이지 첨부 실패 (완전한 워크플로우)**
- 페이지 ID가 정확한지 확인 (대시 포함/제외 무관)
- Integration이 해당 페이지에 접근 권한이 있는지 확인
- 페이지가 삭제되지 않았는지 확인
4. **권한 관련 오류**
- Notion Integration을 페이지에 초대했는지 확인
- 페이지 공유 설정에서 Integration에 편집 권한 부여 확인
## 버전 히스토리
### v2.0.0 (Latest)
- ✅ **완전한 워크플로우** 추가: `upload_and_attach_file_to_page`
- ✅ 한 번의 호출로 파일 업로드 + 페이지 첨부 + 다운로드 URL 획득
- ✅ 구조화된 응답으로 파일 메타데이터 제공
- ✅ 개선된 에러 핸들링 및 디버깅 정보
### v1.0.0
- ✅ 기본 파일 업로드 기능: `upload_file_to_notion`
- ✅ MCP (Model Context Protocol) 서버 구현
- ✅ Claude Desktop 통합 지원