Notion MCP 서버

Notion 통합을 위한 모델 컨텍스트 프로토콜(MCP) 서버 구현으로, Notion API와 상호 작용하기 위한 표준화된 인터페이스를 제공합니다. Claude Desktop 및 기타 MCP 클라이언트와 호환됩니다.

특징

• Notion 데이터베이스 나열 및 쿼리

• 페이지 생성 및 업데이트

• Notion 작업 공간에서 검색

• 데이터베이스 세부 정보를 가져오고 자식을 차단합니다.

• httpx를 통한 완전한 async/await 지원

• Pydantic v2 모델을 사용한 유형 안전

• 자세한 로깅을 통한 적절한 오류 처리

• MCP 1.6.0과의 호환성

Related MCP server: Notion MCP Server

설치

1. 저장소를 복제합니다.

지엑스피1

2. 가상 환경을 만들고 종속성을 설치합니다(uv 사용):

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

또는 표준 venv를 사용하면:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

3. 프로젝트 루트에 .env 파일을 만듭니다.

NOTION_API_KEY=your_notion_integration_token

용법

1. 서버를 테스트합니다(오류 없이 실행되어야 함):

python -m notion_mcp

2. Claude Desktop과 함께 사용하려면 claude_desktop_config.json 파일(macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json 에 위치)을 조정하세요.

{
  "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 models for Notion objects
│       ├── __init__.py        
│       ├── __main__.py        # Entry point
│       ├── client.py          # Notion API client
│       └── server.py          # MCP server implementation
├── .env                       # Environment variables (add your Notion API key here)
├── .gitignore
├── pyproject.toml             # Project dependencies
└── README.md

테스트 실행

pytest

구성

서버에는 Notion 통합 토큰이 필요합니다. 설정하려면 다음 단계를 따르세요.

1. https://www.notion.so/my-integrations 로 이동하세요

2. 적절한 기능(필요에 따라 읽기/쓰기)을 사용하여 새로운 통합을 만듭니다.

3. 통합 토큰을 복사하세요

4. 프로젝트 루트 디렉토리의 .env 파일에 추가하세요.

NOTION_API_KEY=your_notion_integration_token

5. 통합을 통해 Notion 데이터베이스를 공유하세요(데이터베이스의 "공유" 메뉴에서)

기여하다

1. 저장소를 포크하세요

2. 기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )

3. 변경 사항을 커밋하세요( git commit -m 'Add some amazing feature' )

4. 브랜치에 푸시( git push origin feature/amazing-feature )

5. 풀 리퀘스트 열기

특허

MIT 라이선스 - 사용 시 모든 책임은 사용자에게 있습니다.

문제 해결

일반적인 문제

• 연결 오류 : Notion API 키가 올바르고 인터넷에 접속할 수 있는지 확인하세요.

• 권한 오류 : 통합에 액세스하려는 데이터베이스에 대한 액세스 권한이 부여되었는지 확인하세요.

• Claude Desktop 통합 : Claude Desktop이 연결되지 않으면 구성 경로가 올바른지, 서버가 stdout에 로그인하지 않고 실행 중인지 확인하세요.

감사의 말

• Claude Desktop 및 기타 MCP 클라이언트와 함께 작동하도록 제작됨

• Notion의 API를 사용합니다(최신 호환 버전 2022-02-22)

• MCP 1.6.0 호환성 유지됨

• danhilse 에게 특별히 감사드립니다. 저는 그의 notion-mcp-server 프로젝트를 참조했습니다.