Skip to main content
Glama
enesjakozh
awkoy

notion-mcp-server

by awkoy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Notion MCP 서버

특허타입스크립트모델 컨텍스트 프로토콜 대장간 배지 NPM 다운로드별

Notion MCP 서버는 AI 어시스턴트가 Notion API와 상호 작용할 수 있도록 하는 모델 컨텍스트 프로토콜(MCP) 서버 구현입니다. 이 프로덕션 지원 서버는 자연어 상호 작용을 통해 Notion 콘텐츠를 읽고, 생성하고, 수정하기 위한 완전한 도구와 엔드포인트 세트를 제공합니다.

🚧 활발한 개발 : 데이터베이스 지원이 시작되었습니다! 댓글과 사용자 관리 도구가 추가되었습니다. 이 프로젝트가 유용하다고 생각되시면 별점을 남겨주세요. 이 작업이 커뮤니티에 가치 있다는 것을 알게 되고, 더 발전하는 데 동기를 부여합니다.

📑 목차

Related MCP server: Notion MCP Server

🚀 시작하기 및 통합

설정 프로세스

  1. Notion API 키 얻기

  2. 페이지에 대한 통합 활성화

    • 기존 페이지를 선택하거나 Notion에서 새 페이지를 만드세요

    • 오른쪽 상단의 "..." 메뉴를 클릭하세요

    • "연결"로 이동

    • 목록에서 통합을 찾아 활성화하세요Notion 페이지 연결

  3. 통합 방법을 선택하세요

    • 선호하는 MCP 클라이언트에 따라 아래 통합 옵션 중 하나를 따르세요.

  4. AI 비서에게 Notion과의 상호 작용을 요청하세요

    • "오늘의 할 일로 새 페이지를 만들어 보세요"

    • "Notion에서 회의 노트 업데이트"

    • "회의록 페이지에 요점 추가"

    • "프로젝트 추적을 위한 새로운 데이터베이스 생성"

    • "내 작업 데이터베이스에 새 항목을 추가합니다"

    • "내 프로젝트 페이지에 댓글을 추가하세요"

    • "이 문서에 대한 모든 주석을 보여주세요"

    • "내 작업 공간에 있는 모든 사용자 나열"

    • "특정 사용자에 대한 정보를 얻으세요"

커서 통합

방법 1: mcp.json 사용

  1. 프로젝트 디렉토리에서 .cursor/mcp.json 파일을 만들거나 편집하세요.

지엑스피1

  1. YOUR_KEY 및 YOUR_PAGE_ID 실제 Notion API 키 및 페이지 ID로 바꾸세요.

  2. 변경 사항을 적용하려면 커서를 다시 시작하세요.

방법 2: 수동 모드

  1. 커서를 열고 설정으로 이동하세요

  2. "MCP" 또는 "모델 컨텍스트 프로토콜" 섹션으로 이동합니다.

  3. "서버 추가" 또는 이와 동등한 것을 클릭하세요.

  4. 해당 필드에 다음 명령을 입력하세요.

env NOTION_TOKEN=YOUR_KEY NOTION_PAGE_ID=YOUR_PAGE_ID npx -y notion-mcp-server

  1. YOUR_KEY 및 YOUR_PAGE_ID 실제 Notion API 키 및 페이지 ID로 바꾸세요.

  2. 설정을 저장하고 필요한 경우 커서를 다시 시작하세요.

Claude 데스크톱 통합

  1. 구성 디렉토리에서 mcp.json 파일을 만들거나 편집하세요.

{
  "mcpServers": {
    "notion-mcp-server": {
      "command": "npx",
      "args": ["-y", "notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "YOUR_KEY",
        "NOTION_PAGE_ID": "YOUR_PAGE_ID"
      }
    }
  }
}

  1. YOUR_KEY 및 YOUR_PAGE_ID 실제 Notion API 키 및 페이지 ID로 바꾸세요.

  2. 변경 사항을 적용하려면 Claude Desktop을 다시 시작하세요.

🌟 특징

  • 📝 Notion 통합 - Notion 데이터베이스, 페이지 및 블록과 상호 작용

  • 🔌 범용 MCP 호환성 - Cursor, Claude Desktop, Cline, Zed를 포함한 모든 MCP 클라이언트와 호환됩니다.

  • 🔍 데이터 검색 - Notion 페이지, 블록 및 데이터베이스에서 정보 가져오기

  • ✏️ 콘텐츠 생성 - Notion 페이지와 블록을 생성하고 업데이트합니다.

  • 📊 블록 관리 - Notion 페이지 내에서 블록을 추가, 업데이트 및 삭제합니다.

  • 💾 데이터베이스 작업 - 데이터베이스 생성, 쿼리 및 업데이트

  • 🔄 일괄 작업 - 단일 요청으로 여러 작업 수행

  • 🗑️ 보관 및 복원 - Notion 페이지 보관 및 복원

  • 🔎 검색 기능 - 제목으로 Notion 페이지 및 데이터베이스 검색

  • 💬 댓글 관리 - 페이지 및 토론에서 댓글을 받고, 작성하고, 답변하세요.

  • 👥 사용자 관리 - 작업 공간 사용자 및 사용자 정보 검색

📚 문서

사용 가능한 도구

서버는 Notion과 상호 작용하기 위한 다음과 같은 통합 도구를 제공합니다.

notion_pages

다음을 포함한 페이지 작업을 위한 포괄적인 도구:

  • 지정된 콘텐츠로 새 페이지 만들기

  • 페이지 속성 업데이트

  • 페이지 보관(휴지통으로 이동)

  • 이전에 보관된 페이지 복원

  • 제목으로 페이지 검색

예제 작업:

{
  "payload": {
    "action": "create_page", // One of: "create_page", "archive_page", "restore_page", "search_pages", "update_page_properties"
    "params": {
      // Parameters specific to the chosen action
    }
  }
}

notion_blocks

다음을 포함한 블록 작업을 위한 완벽한 툴킷:

  • 블록 콘텐츠 검색

  • 자식 블록 가져오기

  • 부모에 새 블록 추가

  • 기존 블록 업데이트

  • 블록 삭제

  • 일괄 작업 수행(추가, 업데이트, 삭제, 혼합)

예제 작업:

{
  "payload": {
    "action": "append_block_children", // One of: "append_block_children", "retrieve_block", "retrieve_block_children", "update_block", "delete_block", "batch_append_block_children", "batch_update_blocks", "batch_delete_blocks", "batch_mixed_operations"
    "params": {
      // Parameters specific to the chosen action
    }
  }
}

notion_database

다음을 포함한 데이터베이스 상호작용을 위한 강력한 도구:

  • 사용자 정의 속성을 사용하여 새 데이터베이스 만들기

  • 필터 및 정렬을 사용하여 데이터베이스 쿼리

  • 데이터베이스 구조 및 속성 업데이트

예제 작업:

{
  "payload": {
    "action": "create_database", // One of: "create_database", "query_database", "update_database"
    "params": {
      // Parameters specific to the chosen action
    }
  }
}

notion_comments

Notion 콘텐츠에 대한 댓글을 관리하는 도구:

  • 페이지 및 블록에서 댓글 검색

  • 페이지에 새로운 댓글 추가

  • 기존 토론에 답변하기

예제 작업:

{
  "payload": {
    "action": "get_comments", // One of: "get_comments", "add_page_comment", "add_discussion_comment"
    "params": {
      // Parameters specific to the chosen action
    }
  }
}

notion_users

사용자 정보에 접근하기 위한 도구:

  • 모든 작업 공간 사용자 나열

  • 특정 사용자에 대한 세부 정보 얻기

  • 현재 봇 사용자에 대한 정보 검색

예제 작업:

{
  "payload": {
    "action": "list_users", // One of: "list_users", "get_user", "get_bot_user"
    "params": {
      // Parameters specific to the chosen action
    }
  }
}

사용 가능한 리소스

현재 서버는 어떠한 리소스도 공개하지 않고 대신 도구 기반 작업에 집중하고 있습니다.

🛠 개발

  1. 저장소 복제

    git clone https://github.com/awkoy/notion-mcp-server.git
cd notion-mcp-server

  2. 종속성 설치

    npm install

  3. 환경 변수 설정

    • 다음을 사용하여 .env 파일을 만듭니다.

      NOTION_TOKEN=your_notion_api_key
NOTION_PAGE_ID=your_notion_page_id

  4. 프로젝트 빌드

    npm run build

  5. 검사기 실행

    npm run inspector

🔧 기술 세부 사항

  • TypeScript 및 MCP SDK(버전 1.7.0+)를 사용하여 빌드됨

  • 공식 Notion API 클라이언트(@notionhq/client v2.3.0+)를 사용합니다.

  • 모델 컨텍스트 프로토콜 사양을 따릅니다.

  • Notion 페이지, 블록 및 데이터베이스에서 CRUD 작업을 위한 도구를 구현합니다.

  • 성능 최적화를 위한 효율적인 일괄 작업 지원

  • Zod 스키마를 사용하여 입력/출력을 검증합니다.

❓ 문제 해결

  • 일반적인 문제

    • 인증 오류 : Notion 토큰에 올바른 권한이 있는지 확인하고 페이지/데이터베이스에 대한 통합이 활성화되어 있는지 확인하세요.

    • 페이지 액세스 문제 : 액세스하려는 페이지에 통합이 추가되었는지 확인하세요.

    • 속도 제한 : Notion API에는 속도 제한이 있습니다. 일괄 작업을 사용하여 요청을 최적화하세요.

  • 도움 받기

🤝 기여하기

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

  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 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

Available Tools

2 tools
notion_describeNotion DescribeA
Read-only

Return the JSON Schema and a working example for one operation. Use this BEFORE notion_execute when the payload shape is non-trivial (query filters, structured block trees, database property definitions). For simple ops, just call notion_execute — its errors carry the schema.

ParametersJSON Schema
NameRequiredDescriptionDefault
operationYesOperation name to describe.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true; description adds that it returns schema and example without contradicting. No additional behavioral traits needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words, information front-loaded. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description fully explains what it returns and when to use it. Complete and appropriately sized.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter, so baseline is 3. Description adds no additional meaning beyond the schema, which is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it returns 'JSON Schema and a working example for one operation', which clearly defines the action and resource. It also distinguishes from the sibling tool notion_execute.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear guidance: use BEFORE notion_execute for non-trivial payloads, otherwise just call notion_execute. Includes explicit alternatives and when-not-to-use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notion_executeNotion ExecuteA
Destructive

Execute a Notion operation by name.

Two ways to call: • Single: { operation: "set_page_title", payload: { page_id, title } } • Batch: { operation: "set_page_title", payload: { items: [{page_id, title}, ...], atomic?: false, idempotency_key?: "...", concurrency?: 3 } }

If the payload is malformed, the error response includes the full schema + a working example so you can correct and retry in one round-trip. Call notion_describe(operation) ahead of time only for complex shapes (query_database filters, batch_mixed_blocks).

Most responses are slimmed by default. Pass verbose:true inside payload (single) or per-item (batch) to get the raw Notion SDK response.

ParametersJSON Schema
NameRequiredDescriptionDefault
payloadYesOperation parameters. Pass either single-op fields directly, or { items: [...], atomic?, idempotency_key?, concurrency? } for batch.
operationYesOperation name. See notion_describe for the schema of any operation, or read the notion://operations resource for the full menu. Common ops: set_page_title, append_blocks, get_page, search_pages, query_database.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses default slimmed responses, optional verbose mode, batch features (atomic, idempotency_key, concurrency), and error response behavior. Annotations indicate destructiveHint=true and openWorldHint=true, and the description adds valuable operational context without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with bullet points and front-loaded purpose. While every sentence adds value, it could be slightly more concise, but it remains efficient for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex, open-world tool with no output schema, the description thoroughly covers usage patterns (single/batch), response behavior (verbose, slimmed), error handling, and links to companion tool notion_describe. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% but the description enriches both parameters: 'operation' links to notion_describe and lists common ops; 'payload' explains single vs batch structure and optional flags (verbose, atomic, etc.), adding substantial meaning beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Execute a Notion operation by name' and provides concrete examples of single and batch calls. It distinguishes itself from the sibling notion_describe tool, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises when to use notion_describe ('for complex shapes') and when to use this tool directly. Also explains how to handle malformed payloads with automatic schema feedback, guiding effective retries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 15 tool updatesv1.0.1
    • Removedappend_block_children
    • Removedarchive_page
    • Removedbatch_append_block_children
    • Removedbatch_delete_blocks
    • Removedbatch_mixed_operations
    • Removedbatch_update_blocks
    • Removedcreate_page
    • Removeddelete_block
    • Addednotion_describe
    • Addednotion_execute
    • Removedrestore_page
    • Removedretrieve_block
    • Removedretrieve_block_children
    • Removedsearch_pages
    • Removedupdate_block
  2. 13 tool updatesv1.0.0
    • First observedappend_block_children
    • First observedarchive_page
    • First observedbatch_append_block_children
    • First observedbatch_delete_blocks
    • First observedbatch_mixed_operations
    • First observedbatch_update_blocks
    • First observedcreate_page
    • First observeddelete_block
    • First observedrestore_page
    • First observedretrieve_block
    • First observedretrieve_block_children
    • First observedsearch_pages
    • First observedupdate_block
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have distinct, complementary roles: notion_describe provides schema guidance for complex payloads, while notion_execute performs the actual operations. No overlap in purpose.

Naming Consistency5/5

Both tools follow a clear 'notion_' prefix with a verb (describe/execute), maintaining a consistent naming pattern.

Tool Count3/5

With only 2 tools, the server feels minimal for a comprehensive Notion API wrapper. However, the design centralizes operations into notion_execute, which could be suitable if the goal is a thin execution layer.

Completeness2/5

The tool surface lacks explicit representation of common Notion operations (e.g., query database, create page, list blocks). All operations are hidden behind the generic notion_execute tool, making it hard for agents to discover capabilities without external documentation.

Maintenance

ActivityActive
ResponsivenessWithin a week

Resources

Related MCP Connectors

Related MCP Servers

  • Notion MCP Server

    hyunseok-ctrl
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    An MCP server that enables natural language interaction with the Notion API, allowing users to search, comment, create pages, and access content within their Notion workspace.
    135,702
    -

  • notion-mcp-server

    atikk-co-jp
    A
    license
    A
    quality
    C
    maintenance
    An MCP server for Notion API with optimized token efficiency and full database property filtering, enabling AI assistants to manage pages, databases, and blocks.
    32
    40
    1
    MIT

Appeared in Searches