Notion Upload MCP Server

How to use

You can run the MCP server locally and connect to it from your client or automation tool. There are two primary usage patterns you will typically employ:

- Complete workflow: upload a file, attach it to a specific Notion page, and receive a download URL in one request. This provides file metadata and an expiry time so you know when the link will no longer be valid.

- Basic upload: only upload a file and get back the uploaded file’s identifier or URL. This is useful when you plan to attach the file later or only need storage via the Notion API.

How to install

Prerequisites you need on your machine before starting:

• Python 3.8+ (for the MCP server script)
• pip available for installing Python dependencies
• uv (preferred runtime) for running Python MCP modules

Install the MCP package in editable mode and install runtime dependencies if you want to run the server directly from source:

# Install with uv runtime (recommended)
uv sync

# Or install via Python in editable mode
pip install -e .
# Or install dependencies directly
pip install httpx mcp[cli]

Configuring and running the server with Claude Desktop

You can configure the Claude Desktop client to start the MCP server in different ways. Use the following complete command setups to run the MCP script that handles Notion uploads.

{
  "mcpServers": {
    "notion-upload": {
      "command": "uv",
      "args": [
        "sync"
      ],
      "env": {
        "NOTION_API_TOKEN": "secret_your_notion_token_here"
      }
    }
  }
}

Alternative run methods

If you prefer running the script directly or inside a virtual environment, use one of these configurations.

{
  "mcpServers": {
    "notion-upload": {
      "command": "python",
      "args": [
        "/path/to/mcp_notion_upload.py"
      ],
      "env": {
        "NOTION_API_TOKEN": "secret_your_notion_token_here"
      }
    }
  }
}

Environment variables

To avoid entering tokens repeatedly, you can set environment variables for the MCP server. The example shows how to provide the Notion API token up front.

{
  "mcpServers": {
    "notion-upload": {
      "command": "uv",
      "args": [
        "sync"
      ],
      "env": {
        "NOTION_API_TOKEN": "secret_your_notion_token_here"
      }
    }
  }
}

Notion 페이지 ID와 토큰 준비

Notion API 토큰은 Notion Integration에서 생성하며, 파일을 첨부할 페이지의 ID 또한 필요합니다. 페이지 ID는 Notion 페이지 URL의 일부로 나타납니다.

예시 페이지 ID 형식은 다음과 같습니다: 2785bbc0-e5c2-81f4-8dfa-e9a48f53f6a6 또는 2785bbc0e5c281f48dfae9a48f53f6a6.

사용 시 주의사항

- 최대 파일 크기는 20MB입니다.

- 지원 파일 형식은 이미지, PDF, 오디오, 비디오 등입니다.

- 완전한 워크플로우를 사용할 경우 다운로드 URL은 1시간 동안 유효합니다. URL 갱신은 페이지를 다시 조회하면 가능합니다.

- 기본 업로드의 경우 파일은 1시간 이내에 Notion 페이지나 블록에 수동으로 첨부해야 합니다.

- Claude Desktop 설정을 변경한 경우 다시 시작해야 반영됩니다.

- 페이지 첨부 시 해당 페이지에 대한 편집 권한이 필요합니다.

트러블슈팅

- 서버가 실행되지 않는 경우 경로가 절대 경로인지 확인하고, Python/uv 실행 파일 경로가 정확한지 확인하며 필요한 패키지가 설치되었는지 점검합니다.

- 파일 업로드 실패 시 Notion API 토큰이 유효한지 확인하고 파일 크기가 20MB 이하인지, 파일이 실제로 존재하는지 점검합니다.

- 페이지 첨부 실패 시 페이지 ID가 정확하고 Integration에 해당 페이지에 대한 편집 권한이 있는지 확인합니다.

- 권한 관련 오류가 있을 경우 Notion Integration이 페이지에 초대되었는지 확인하고 페이지 공유 설정에서 편집 권한을 부여합니다.

버전 히스토리

v2.0.0 (Latest)에서 완전한 워크플로우가 추가되어 파일 업로드, 페이지 첨부, 다운로드 URL 획득을 한 번의 호출로 처리할 수 있습니다.

v1.0.0에서는 기본 파일 업로드 기능과 MCP 서버의 초석이 제공됩니다.

upload_file_to_notion

Uploads a single file to Notion and returns the public URL of the uploaded file.

upload_and_attach_file_to_page

Performs file upload, attaches the file to a specified Notion page, and returns a structured response including the download URL and metadata.