{ "canonical_name": "makenotion/notion-mcp-server", "compilation_id": "pack_f03d1354428a474da44aa1eb54114d07", "created_at": "2026-05-16T23:55:57.270270+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight", "recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npx @notionhq/notion-mcp-server` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npx @notionhq/notion-mcp-server", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_51b5de7cb47e487a98a3df8421b43c16" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_156f9924bda5b004c930694c89bce508", "canonical_name": "makenotion/notion-mcp-server", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/makenotion/notion-mcp-server", "slug": "notion-mcp-server", "source_packet_id": "phit_37d8ace822fd44888f0126b58a6e004f", "source_validation_id": "dval_8ca90274aa7b4b399787d5d55144dc3a" }, "merchandising": { "best_for": "需要工具连接与集成能力，并使用 mcp_host的用户", "github_forks": 568, "github_stars": 4334, "one_liner_en": "Official Notion MCP Server", "one_liner_zh": "Official Notion MCP Server", "primary_category": { "category_id": "tool-integrations", "confidence": "high", "name_en": "Tool Integrations", "name_zh": "工具连接与集成", "reason": "matched_keywords:mcp, server, notion" }, "target_user": "使用 mcp_host 等宿主 AI 的用户", "title_en": "notion-mcp-server", "title_zh": "notion-mcp-server 能力包", "visible_tags": [ { "label_en": "MCP Tools", "label_zh": "MCP 工具", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-mcp-tools", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "Workflow Automation", "label_zh": "流程自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-workflow-automation", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_37d8ace822fd44888f0126b58a6e004f", "page_model": { "artifacts": { "artifact_slug": "notion-mcp-server", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npx @notionhq/notion-mcp-server", "label": "Node.js / npx · 官方安装入口", "source": "https://github.com/makenotion/notion-mcp-server#readme", "verified": true } ], "display_tags": [ "MCP 工具", "知识库问答", "流程自动化", "节点式流程编排", "评测体系" ], "eyebrow": "工具连接与集成", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要工具连接与集成能力，并使用 mcp_host的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "Official Notion MCP Server" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "mcp_host", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "mcp_config, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：BUG: Tool `query_data_sources` not available", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_eef5bea2e30f4ef6b0ebbec184ad57bc | https://github.com/makenotion/notion-mcp-server/issues/256 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：BUG: Tool `query_data_sources` not available", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_e292459f0a6b4c38ab30d85d1fed7988 | https://github.com/makenotion/notion-mcp-server/issues/232 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missing POST /v1/databases tool", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_00471efb0dd04e9a998d767773687158 | https://github.com/makenotion/notion-mcp-server/issues/218 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_c42a4b966290466e9d4c8678f1530d70 | https://github.com/makenotion/notion-mcp-server/issues/269 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Notion MCP server does not work with Claude Code", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_f225074bf40440978c5542d0a0553a33 | https://github.com/makenotion/notion-mcp-server/issues/277 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Notion MCP server does not work with Claude Code", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token expires too frequently — requires re-authentication 3+ times per week", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_6e81d503097248cb8099528ad547bc67 | https://github.com/makenotion/notion-mcp-server/issues/225 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：OAuth token expires too frequently — requires re-authentication 3+ times per week", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Property-based filtering in notion-search for database queries", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_b9e32ab88c7e48818bc99b84652be1ab | https://github.com/makenotion/notion-mcp-server/issues/278 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Feature Request: Property-based filtering in notion-search for database queries", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ontheia listed as compatible client — works great with notion-mcp-server", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_3fc1b045a8d44d0fb100ada453a88281 | https://github.com/makenotion/notion-mcp-server/issues/287 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Ontheia listed as compatible client — works great with notion-mcp-server", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_cf7210b63f984b539554678f387c7e82 | https://github.com/makenotion/notion-mcp-server/issues/283 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Expand blockObjectRequest to support all Notion block types", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_1dca271be3594278a2b6cae74a5a3caf | https://github.com/makenotion/notion-mcp-server/issues/282 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Enhancement: Expand blockObjectRequest to support all Notion block types", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_6ed1925ce08546dabe29e4f24e8a5967 | https://github.com/makenotion/notion-mcp-server/issues/281 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Schema quality: 8 required parameters missing descriptions", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_3874c96ff07545e58a89907777de0799 | https://github.com/makenotion/notion-mcp-server/issues/280 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Schema quality: 8 required parameters missing descriptions", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag", "category": "维护坑", "evidence": [ "community_evidence:github | cevd_201ffa8849a546d7aa12e1ea13455afb | https://github.com/makenotion/notion-mcp-server/issues/286 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 21 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：配置坑 - 来源证据：BUG: Tool `query_data_sources` not available。", "title": "踩坑日志" }, "snapshot": { "contributors": 22, "forks": 568, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 4334 }, "source_url": "https://github.com/makenotion/notion-mcp-server", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "Official Notion MCP Server", "title": "notion-mcp-server 能力包", "trial_prompt": "# notion-mcp-server - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for makenotion/notion-mcp-server.\n\nProject:\n- Name: notion-mcp-server\n- Repository: https://github.com/makenotion/notion-mcp-server\n- Summary: Official Notion MCP Server\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Official Notion MCP Server\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Official Notion MCP Server\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-introduction: Introduction to Notion MCP Server. Produce one small intermediate artifact and wait for confirmation.\n2. page-quickstart: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. page-transport-layers: Transport Layers. Produce one small intermediate artifact and wait for confirmation.\n5. page-available-tools: Available MCP Tools. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/makenotion/notion-mcp-server\n- https://github.com/makenotion/notion-mcp-server#readme\n- README.md\n- package.json\n- CLAUDE.md\n- src/init-server.ts\n- src/openapi-mcp-server/index.ts\n- src/openapi-mcp-server/client/http-client.ts\n- src/openapi-mcp-server/openapi/parser.ts\n- src/openapi-mcp-server/auth/index.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: Ontheia listed as compatible client — works great with notion-mcp-server（https://github.com/makenotion/notion-mcp-server/issues/287）；github/github_issue: synced_block_reference: URL inside url= attribute gets auto-converted to（https://github.com/makenotion/notion-mcp-server/issues/286）；github/github_issue: API-create-a-data-source and API-update-a-data-source return invalid_req（https://github.com/makenotion/notion-mcp-server/issues/218）；github/github_issue: v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not in（https://github.com/makenotion/notion-mcp-server/issues/284）；github/github_issue: Feature Request: Support local file upload for images and files（https://github.com/makenotion/notion-mcp-server/issues/191）；github/github_issue: Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not（https://github.com/makenotion/notion-mcp-server/issues/232）；github/github_issue: Bug: notion-create-view silently drops FILTER on Status property (no err（https://github.com/makenotion/notion-mcp-server/issues/283）；github/github_issue: Enhancement: Expand blockObjectRequest to support all Notion block types（https://github.com/makenotion/notion-mcp-server/issues/282）；github/github_issue: BUG: Tool `query_data_sources` not available（https://github.com/makenotion/notion-mcp-server/issues/256）；github/github_issue: [Bug] FILTER directive in view DSL silently drops filters for Relation a（https://github.com/makenotion/notion-mcp-server/issues/281）；github/github_issue: Schema quality: 8 required parameters missing descriptions（https://github.com/makenotion/notion-mcp-server/issues/280）；github/github_issue: OAuth token expires too frequently — requires re-authentication 3+ times（https://github.com/makenotion/notion-mcp-server/issues/225）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "Ontheia listed as compatible client — works great with notion-mcp-server", "url": "https://github.com/makenotion/notion-mcp-server/issues/287" }, { "kind": "github_issue", "source": "github", "title": "synced_block_reference: URL inside url= attribute gets auto-converted to", "url": "https://github.com/makenotion/notion-mcp-server/issues/286" }, { "kind": "github_issue", "source": "github", "title": "API-create-a-data-source and API-update-a-data-source return invalid_req", "url": "https://github.com/makenotion/notion-mcp-server/issues/218" }, { "kind": "github_issue", "source": "github", "title": "v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not in", "url": "https://github.com/makenotion/notion-mcp-server/issues/284" }, { "kind": "github_issue", "source": "github", "title": "Feature Request: Support local file upload for images and files", "url": "https://github.com/makenotion/notion-mcp-server/issues/191" }, { "kind": "github_issue", "source": "github", "title": "Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not", "url": "https://github.com/makenotion/notion-mcp-server/issues/232" }, { "kind": "github_issue", "source": "github", "title": "Bug: notion-create-view silently drops FILTER on Status property (no err", "url": "https://github.com/makenotion/notion-mcp-server/issues/283" }, { "kind": "github_issue", "source": "github", "title": "Enhancement: Expand blockObjectRequest to support all Notion block types", "url": "https://github.com/makenotion/notion-mcp-server/issues/282" }, { "kind": "github_issue", "source": "github", "title": "BUG: Tool `query_data_sources` not available", "url": "https://github.com/makenotion/notion-mcp-server/issues/256" }, { "kind": "github_issue", "source": "github", "title": "[Bug] FILTER directive in view DSL silently drops filters for Relation a", "url": "https://github.com/makenotion/notion-mcp-server/issues/281" }, { "kind": "github_issue", "source": "github", "title": "Schema quality: 8 required parameters missing descriptions", "url": "https://github.com/makenotion/notion-mcp-server/issues/280" }, { "kind": "github_issue", "source": "github", "title": "OAuth token expires too frequently — requires re-authentication 3+ times", "url": "https://github.com/makenotion/notion-mcp-server/issues/225" } ], "status": "已收录 12 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "工具连接与集成", "desc": "Official Notion MCP Server", "effort": "安装已验证", "forks": 568, "icon": "link", "name": "notion-mcp-server 能力包", "risk": "可发布", "slug": "notion-mcp-server", "stars": 4334, "tags": [ "MCP 工具", "知识库问答", "流程自动化", "节点式流程编排", "评测体系" ], "thumb": "gray", "type": "MCP 配置" }, "manual": { "markdown": "# https://github.com/makenotion/notion-mcp-server 项目说明书\n\n生成时间：2026-05-16 23:53:23 UTC\n\n## 目录\n\n- [Introduction to Notion MCP Server](#page-introduction)\n- [Quick Start Guide](#page-quickstart)\n- [System Architecture](#page-architecture)\n- [Transport Layers](#page-transport-layers)\n- [MCP Proxy Implementation](#page-mcp-proxy)\n- [Available MCP Tools](#page-available-tools)\n- [Data Sources (v2.0.0 Breaking Changes)](#page-data-sources-v2)\n- [Authentication System](#page-authentication)\n- [npm Installation and Configuration](#page-npm-installation)\n- [Docker Deployment](#page-docker-deployment)\n\n\n\n## Introduction to Notion MCP Server\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#page-quickstart), [System Architecture](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n
\n\n# Introduction to Notion MCP Server\n\nThe Notion MCP Server is an official implementation of the [Model Context Protocol (MCP)](https://spec.modelcontextprotocol.io/) server that exposes the [Notion API](https://developers.notion.com/reference/intro) as MCP tools. It enables AI assistants and agents to interact with Notion workspaces through a standardized protocol, allowing them to search, read, create, and modify Notion pages, databases, and content.\n\n## Overview\n\nThe MCP server acts as a bridge between AI clients (such as Claude, Cursor, or GitHub Copilot) and the Notion API. Instead of manually implementing API calls, AI agents can discover and invoke MCP tools dynamically, making it easier to build AI-powered Notion integrations.\n\n### Key Characteristics\n\n| Attribute | Value |\n|-----------|-------|\n| **Package Name** | `@notionhq/notion-mcp-server` |\n| **Current Version** | 2.3.0 |\n| **License** | MIT |\n| **API Version** | 2025-09-03 (Data Source Edition) |\n| **Node.js Support** | 18+ (with Headers polyfill for older versions) |\n| **Transport Modes** | stdio, Streamable HTTP |\n| **Total Tools** | 22 |\n\n资料来源：[README.md:1-30]()[package.json:7-10]()\n\n## Architecture\n\nThe Notion MCP Server follows a layered architecture that auto-generates tools from an OpenAPI specification. This design ensures that any updates to the Notion API are automatically reflected in the available MCP tools without requiring code changes.\n\n### High-Level Flow\n\n```mermaid\ngraph TD\n A[scripts/notion-openapi.json] --> B[OpenAPIToMCPConverter]\n B --> C[MCPProxy]\n C --> D[MCP SDK]\n D --> E[AI Client]\n \n F[User Request] --> E\n E --> G[Tool Call]\n G --> H[HTTP Client]\n H --> I[Notion API]\n I --> H --> G --> F\n```\n\n资料来源：[CLAUDE.md:1-30]()\n\n### Component Architecture\n\n```mermaid\ngraph TD\n subgraph \"Entry Point\"\n A[scripts/start-server.ts]\n end\n \n subgraph \"Server Initialization\"\n B[src/init-server.ts]\n end\n \n subgraph \"Core Implementation\"\n C[openapi/parser.ts]\n D[mcp/proxy.ts]\n E[client/http-client.ts]\n end\n \n A --> B --> C\n C --> D\n D --> E\n E --> F[Notion API]\n```\n\nThe server initialization process follows these steps:\n\n1. **Load OpenAPI Spec**: The server loads `scripts/notion-openapi.json` which defines all Notion API endpoints in OpenAPI 3.1.0 format\n2. **Validate Spec**: The spec is validated against OpenAPI schema requirements\n3. **Create MCPProxy**: A new MCPProxy instance is created with the validated spec\n4. **Register Tools**: `MCPProxy.setupHandlers()` registers all discovered tools with the MCP SDK\n5. **Start Transport**: The server starts listening on the configured transport (stdio or HTTP)\n\n资料来源：[CLAUDE.md:15-45]()[scripts/start-server.ts:1-50]()\n\n### Tool Generation Flow\n\nTools are automatically generated from the OpenAPI specification through a conversion process:\n\n```mermaid\ngraph LR\n A[OpenAPI Operation] --> B[Extract operationId]\n B --> C[Parse Parameters]\n C --> D[Parse Request Body]\n D --> E[Parse Response Schema]\n E --> F[Create MCP Tool]\n \n G[Path + Method] --> A\n H[inputSchema] --> F\n I[returnSchema] --> F\n```\n\n1. `OpenAPIToMCPConverter.convertToMCPTools()` iterates through all paths and operations in the OpenAPI spec\n2. Each operation becomes an MCP tool where the name is derived from `operationId`\n3. Operation parameters and request body are combined into the tool's `inputSchema`\n4. The response schema becomes the tool's `returnSchema`\n5. `MCPProxy.setupHandlers()` registers the tools with the MCP SDK\n\n资料来源：[CLAUDE.md:30-50]()[src/openapi-mcp-server/openapi/parser.ts:1-50]()\n\n## File Structure\n\nThe repository is organized as follows:\n\n```\nnotion-mcp-server/\n├── scripts/\n│ ├── notion-openapi.json # OpenAPI 3.1.0 specification\n│ └── start-server.ts # CLI entry point\n├── src/\n│ ├── init-server.ts # Server initialization\n│ └── openapi-mcp-server/\n│ ├── openapi/\n│ │ └── parser.ts # OpenAPI to MCP conversion\n│ ├── mcp/\n│ │ └── proxy.ts # Tool registration & execution\n│ └── client/\n│ ├── http-client.ts # HTTP request execution\n│ └── polyfill-headers.ts # Node.js Headers polyfill\n├── bin/\n│ └── cli.mjs # Bundled CLI\n└── package.json # Package configuration\n```\n\n| File | Purpose | Lines |\n|------|---------|-------|\n| `scripts/notion-openapi.json` | Source of truth for all tools | - |\n| `src/init-server.ts` | Loads & validates spec, creates MCPProxy | - |\n| `src/openapi-mcp-server/openapi/parser.ts` | Converts OpenAPI → MCP tools | ~529 |\n| `src/openapi-mcp-server/mcp/proxy.ts` | MCP tool registration and execution | ~209 |\n| `src/openapi-mcp-server/client/http-client.ts` | Executes API calls via axios | ~198 |\n\n资料来源：[CLAUDE.md:50-65]()\n\n## Installation and Configuration\n\n### Prerequisites\n\n- Node.js 18 or higher\n- A Notion integration token (from [Notion integrations page](https://www.notion.so/profile/integrations))\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `NOTION_TOKEN` | Notion integration secret (recommended) | Yes |\n| `OPENAPI_MCP_HEADERS` | JSON string with custom headers | Alternative |\n| `AUTH_TOKEN` | Bearer token for HTTP transport authentication | For HTTP mode |\n| `NOTION_API_URL` | Override Notion API base URL | No |\n\n资料来源：[README.md:80-120]()\n\n### npm Installation\n\nFor Cursor, Claude Desktop, and similar clients:\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\nFor Zed editor:\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"]\n },\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\"}\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:100-140]()\n\n### Docker Installation\n\nUsing the official Docker Hub image:\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"NOTION_TOKEN\", \"mcp/notion\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\nOr building locally with docker-compose:\n\n```bash\ndocker compose build\n```\n\n资料来源：[README.md:180-220]()\n\n## Transport Modes\n\nThe server supports two transport modes for communication with MCP clients.\n\n### Standard I/O (stdio)\n\nThe default transport mode where the server communicates via stdin/stdout. This is suitable for local integrations and most IDE plugins.\n\n```bash\nnpx @notionhq/notion-mcp-server\n# or\nnotion-mcp-server\n```\n\n资料来源：[README.md:70-80]()\n\n### Streamable HTTP\n\nAn HTTP-based transport that enables remote connections and is suitable for network deployments.\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --port 3000\n```\n\nWhen using HTTP transport, the server is available at `http://0.0.0.0:/mcp`.\n\n#### HTTP Authentication\n\nThe HTTP transport requires bearer token authentication:\n\n| Method | Description |\n|--------|-------------|\n| Auto-generated token | `npx @notionhq/notion-mcp-server --transport http` |\n| CLI argument | `--auth-token \"your-secret-token\"` |\n| Environment variable | `AUTH_TOKEN=\"your-secret-token\"` |\n\nExample authenticated request:\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n资料来源：[scripts/start-server.ts:1-50]()[README.md:150-175]()\n\n## Available Tools\n\nThe server exposes 22 MCP tools generated from the Notion API OpenAPI specification. Tools are named using the `operationId` from the OpenAPI spec.\n\n### Tool Naming Convention\n\n- Tool names are derived from the OpenAPI `operationId` (e.g., `retrieve-a-database`)\n- Names are truncated to 64 characters and converted to title case for display\n- Parameters and response schemas are automatically extracted from the OpenAPI specification\n\n资料来源：[CLAUDE.md:45-50]()\n\n### Core Operations\n\n| Category | Example Tools |\n|----------|---------------|\n| **Pages** | `create-a-page`, `retrieve-a-page`, `update-a-page`, `archive-a-page`, `move-page` |\n| **Databases** | `retrieve-a-database`, `query-a-database` |\n| **Data Sources** | `create-a-data-source`, `retrieve-a-data-source`, `update-a-data-source`, `query-data-source`, `list-data-source-templates` |\n| **Search** | `search` |\n| **Comments** | `create-a-comment`, `retrieve-comments` |\n| **Users** | `list-users`, `retrieve-a-user` |\n| **Blocks** | Various block operations |\n\n### Version 2.0.0 Breaking Changes\n\nVersion 2.0.0 introduced significant changes to align with the Notion API 2025-09-03 (Data Source Edition):\n\n#### Removed Tools\n\n| Old Tool | Reason |\n|----------|--------|\n| `post-database-query` | Replaced by `query-data-source` |\n| `update-a-database` | Replaced by `update-a-data-source` |\n| `create-a-database` | Replaced by `create-a-data-source` |\n\n#### New Tools\n\n| New Tool | Description |\n|----------|-------------|\n| `query-data-source` | Query a data source with filters and sorts |\n| `retrieve-a-data-source` | Get metadata and schema for a data source |\n| `update-a-data-source` | Update data source properties |\n| `create-a-data-source` | Create a new data source |\n| `list-data-source-templates` | List available templates in a data source |\n| `move-page` | Move a page to a different parent location |\n| `retrieve-a-database` | Get database metadata including data source IDs |\n\n#### Parameter Changes\n\n| Change | Description |\n|--------|-------------|\n| `database_id` → `data_source_id` | All database operations now use data source ID |\n| Search filter values | Changed from `[\"page\", \"database\"]` to `[\"page\", \"data_source\"]` |\n| Page creation | Now supports both `page_id` and `database_id` parents |\n\n资料来源：[README.md:35-80]()\n\n## Parameter Handling\n\nThe MCP server includes sophisticated parameter deserialization to handle complex nested data structures passed through MCP clients.\n\n### JSON String Deserialization\n\nWhen AI clients pass JSON data as string parameters, the server automatically parses them:\n\n```mermaid\ngraph TD\n A[String Parameter] --> B{Starts with { or [?}\n B -->|Yes| C[Attempt JSON.parse]\n C --> D{Parse Success?}\n D -->|Yes| E{Result is Object/Array?}\n E -->|Yes| F[Return parsed value]\n E -->|No| G[Keep original string]\n D -->|No| G\n B -->|No| G\n```\n\nThis logic handles:\n- JSON objects passed as strings\n- JSON arrays passed as strings\n- Nested objects within arrays\n- Recursively nested objects\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:1-60]()\n\n## Development\n\n### Build and Test\n\n```bash\nnpm run build # TypeScript compilation + CLI bundling\nnpm test # Run vitest tests\nnpm run dev # Start dev server with hot reload\n```\n\n### Testing Changes Locally\n\n1. Run `npm link` from the repository root to create a machine-global symlink\n2. Add the following to your MCP client's configuration:\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n3. Cleanup by running `npm unlink` from the repository root\n\n### Adding New Endpoints\n\nThe architecture is designed so that **only `scripts/notion-openapi.json` needs to be modified** to add new tools. The tool generation is fully automated from the OpenAPI specification.\n\n资料来源：[README.md:250-280]()[CLAUDE.md:20-30]()\n\n### CLI Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--transport ` | Transport type: 'stdio' or 'http' | stdio |\n| `--port ` | Port for HTTP server | 3000 |\n| `--auth-token ` | Bearer token for HTTP auth | auto-generated |\n| `--disable-auth` | Disable HTTP bearer auth | - |\n| `--help`, `-h` | Show help message | - |\n\n```bash\n# Examples\nnotion-mcp-server # stdio (default)\nnotion-mcp-server --transport http # HTTP transport\nnotion-mcp-server --transport http --port 8080 # Custom port\nnotion-mcp-server --transport http --auth-token abc # With auth\n```\n\n资料来源：[scripts/start-server.ts:1-50]()\n\n## HTTP Client Implementation\n\nThe HTTP client uses axios for making requests to the Notion API and handles the conversion between MCP tool parameters and HTTP request components.\n\n### Request Processing Flow\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Client\n participant Server as MCP Server\n participant HTTP as HTTP Client\n participant Notion as Notion API\n \n MCP->>Server: Tool Call with params\n Server->>Server: Extract URL params\n Server->>Server: Extract body params\n Server->>HTTP: Build request config\n HTTP->>Notion: HTTP Request\n Notion-->>HTTP: Response\n HTTP-->>Server: Parsed response\n Server-->>MCP: Tool result\n```\n\n### Key Implementation Details\n\n- **Form Data Handling**: When form data is present, `formData.getHeaders()` is used for correct Content-Type\n- **Body Parameters**: JSON body is sent with `Content-Type: application/json`\n- **Header Conversion**: Axios response headers are converted to standard `Headers` objects\n- **Error Handling**: Missing operations throw descriptive errors\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-80]()\n\n## Dependencies\n\n| Dependency | Version | Purpose |\n|------------|---------|---------|\n| `@modelcontextprotocol/sdk` | ^1.25.1 | MCP protocol implementation |\n| `axios` | ^1.8.4 | HTTP client for Notion API |\n| `express` | ^4.21.2 | HTTP transport server |\n| `form-data` | ^4.0.1 | Multipart form handling |\n| `openapi-client-axios` | ^7.5.5 | OpenAPI client generation |\n| `yargs` | ^17.7.2 | CLI argument parsing |\n| `zod` | 3.24.1 | Schema validation |\n\n资料来源：[package.json:25-45]()\n\n## Future Considerations\n\n> [!NOTE]\n>\n> Notion has introduced **Notion MCP** (remote), a new remote MCP server with OAuth-based authentication and tools optimized for AI agents, including Markdown editing capabilities.\n>\n> The local MCP server repository may be sunset in the future. Issues and pull requests are not actively monitored. For the remote MCP server, please contact Notion support.\n\n资料来源：[README.md:1-25]()\n\n## Quick Reference\n\n### Common Commands\n\n```bash\n# Install and run\nnpx @notionhq/notion-mcp-server\n\n# Build from source\nnpm run build\nnpm test\n\n# Development\nnpm run dev\nnpm link # For local testing\n```\n\n### Integration Setup Checklist\n\n- [ ] Create Notion integration at [notion.so/profile/integrations](https://www.notion.so/profile/integrations)\n- [ ] Share target pages with the integration (Connections)\n- [ ] Configure MCP client with `NOTION_TOKEN` or `OPENAPI_MCP_HEADERS`\n- [ ] Test connectivity with a simple search or retrieval\n\n### File Paths Reference\n\n| Path | Description |\n|------|-------------|\n| `scripts/notion-openapi.json` | OpenAPI 3.1.0 spec for all tools |\n| `src/init-server.ts` | Server initialization |\n| `src/openapi-mcp-server/openapi/parser.ts` | OpenAPI → MCP conversion |\n| `src/openapi-mcp-server/mcp/proxy.ts` | Tool registration |\n| `src/openapi-mcp-server/client/http-client.ts` | API request execution |\n| `bin/cli.mjs` | Bundled CLI entry point |\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Introduction to Notion MCP Server](#page-introduction), [Authentication System](#page-authentication), [npm Installation and Configuration](#page-npm-installation)\n\n
\nRelated Source Files\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n
\n\n# Quick Start Guide\n\nThis guide provides everything you need to get started with the Notion MCP Server, from installation to running your first AI-assisted Notion operations.\n\n## Overview\n\nThe **Notion MCP Server** is a Model Context Protocol (MCP) server that exposes the Notion API as MCP tools, enabling AI assistants to interact with Notion workspaces. It auto-generates tools from an OpenAPI specification, providing 22 tools for operations like searching pages, creating content, querying databases, and managing comments.\n\n资料来源：[CLAUDE.md:1-10]()\n\n### Architecture\n\nThe server transforms the Notion REST API into an MCP-compatible interface:\n\n```mermaid\ngraph TD\n A[\"scripts/notion-openapi.json
OpenAPI 3.1.0 Spec\"] --> B[\"OpenAPIToMCPConverter\"]\n B --> C[\"MCP Tools
22 Tools Generated\"]\n C --> D[\"MCPProxy.setupHandlers()\"]\n D --> E[\"HttpClient
API Execution\"]\n E --> F[\"Notion API
https://api.notion.com\"]\n```\n\n### Tool Generation Flow\n\n| Step | Component | Description |\n|------|-----------|-------------|\n| 1 | OpenAPI Spec | Iterates all paths and operations |\n| 2 | Operation → Tool | Each operationId becomes a tool name |\n| 3 | Parameters | Converted to `inputSchema` |\n| 4 | Response | Converted to `returnSchema` |\n| 5 | Registration | `MCPProxy.setupHandlers()` registers with SDK |\n\n资料来源：[CLAUDE.md:32-38]()\n\n## Prerequisites\n\nBefore getting started, ensure you have:\n\n- **Node.js** 18+ (for native `Headers` support)\n- **npm** or **yarn** package manager\n- A **Notion integration** with an API token\n- Access to Notion pages you want the integration to access\n\n资料来源：[src/openapi-mcp-server/client/polyfill-headers.ts:1-5]()\n\n## Installation\n\n### Option 1: Using npm (Recommended)\n\nRun the server directly with `npx`:\n\n```bash\nnpx -y @notionhq/notion-mcp-server\n```\n\n资料来源：[README.md:1-5]()\n\n### Option 2: Using Docker\n\n#### Option 2a: Official Docker Hub Image\n\n```bash\ndocker run --rm -i \\\n -e NOTION_TOKEN=ntn_**** \\\n mcp/notion\n```\n\n#### Option 2b: Build Locally\n\n```bash\ndocker compose build\ndocker run --rm -i \\\n -e NOTION_TOKEN=ntn_**** \\\n notion-mcp-server\n```\n\n资料来源：[README.md:2-25]()\n\n### Option 3: Local Development\n\n```bash\ngit clone https://github.com/makenotion/notion-mcp-server.git\ncd notion-mcp-server\nnpm install\n```\n\n资料来源：[package.json:1-20]()\n\n## Configuration\n\n### Step 1: Create a Notion Integration\n\n1. Go to [https://www.notion.so/profile/integrations](https://www.notion.so/profile/integrations)\n2. Create a new **internal** integration or select an existing one\n3. Copy the integration token (starts with `ntn_`)\n\n资料来源：[README.md:1-8]()\n\n### Step 2: Grant Page Access\n\nFor each Notion page you want the integration to access:\n\n1. Open the target page\n2. Click the **three dots menu** (⋯)\n3. Select **\"Connect to integration\"**\n\n资料来源：[README.md:1-5]()\n\n### Step 3: Configure Your MCP Client\n\n#### Cursor & Claude Desktop\n\nAdd to `.cursor/mcp.json` or `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n#### Zed\n\nAdd to `settings.json`:\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\"}\"\n }\n },\n \"settings\": {}\n }\n }\n}\n```\n\n#### GitHub Copilot CLI\n\n```bash\n/mcp add\n```\n\nOr edit `~/.copilot/mcp-config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:1-70]()\n\n## Authentication\n\n### Environment Variables\n\n| Variable | Description | Priority |\n|----------|-------------|----------|\n| `NOTION_TOKEN` | Integration token (recommended) | Primary |\n| `OPENAPI_MCP_HEADERS` | JSON string with custom headers | Alternative |\n| `AUTH_TOKEN` | Bearer token for HTTP transport | Lower |\n\n资料来源：[scripts/start-server.ts:1-30]()\n\n### HTTP Transport Authentication\n\nWhen using the Streamable HTTP transport, bearer token authentication is required:\n\n```bash\n# Auto-generated token (development only)\nnpx @notionhq/notion-mcp-server --transport http\n\n# Custom token via CLI (recommended for production)\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n\n# Custom token via environment variable\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq/notion-mcp-server --transport http\n```\n\nThe `--auth-token` CLI argument takes precedence over the `AUTH_TOKEN` environment variable.\n\n资料来源：[scripts/start-server.ts:1-35]()\n\n### Making HTTP Requests\n\nAll requests must include the bearer token:\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n资料来源：[README.md:1-15]()\n\n## Command Line Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--transport ` | Transport type: `stdio` or `http` | `stdio` |\n| `--port ` | Port for HTTP server | `3000` |\n| `--auth-token ` | Bearer token for HTTP authentication | Auto-generated |\n| `--disable-auth` | Disable authentication for HTTP transport | `false` |\n| `--help`, `-h` | Show help message | - |\n\n资料来源：[scripts/start-server.ts:1-25]()\n\n### Usage Examples\n\n```bash\n# Default stdio transport\nnotion-mcp-server\n\n# Explicit stdio transport\nnotion-mcp-server --transport stdio\n\n# HTTP transport with custom port\nnotion-mcp-server --transport http --port 8080\n\n# HTTP transport with custom auth token\nnotion-mcp-server --transport http --auth-token \"my-secret\"\n```\n\n## Available Tools\n\nThe server exposes 22 MCP tools auto-generated from the Notion API. Key tools include:\n\n| Tool | Description | Version Change |\n|------|-------------|----------------|\n| `query-data-source` | Query a data source with filters and sorts | **New in v2.0** |\n| `retrieve-a-data-source` | Get metadata and schema for a data source | **New in v2.0** |\n| `create-a-data-source` | Create a new data source | **New in v2.0** |\n| `update-a-data-source` | Update data source properties | **New in v2.0** |\n| `move-page` | Move a page to a different parent | **New in v2.0** |\n| `list-data-source-templates` | List available templates in a data source | **New in v2.0** |\n| `retrieve-a-database` | Get database metadata including data source IDs | **New in v2.0** |\n| `search` | Search pages and data sources | Updated filter values |\n\n> **Note:** In v2.0.0, `database_id` parameters changed to `data_source_id` for data source operations.\n\n资料来源：[CLAUDE.md:1-20]()\n\n## Development\n\n### Build & Test\n\n```bash\nnpm run build # TypeScript compilation + CLI bundling\nnpm test # Run vitest tests\nnpm run dev # Start dev server with hot reload\n```\n\n### Testing Local Changes in Cursor\n\n1. Run `npm link` from repository root to create a machine-global symlink\n2. Add to Cursor's `mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n3. **Cleanup:** Run `npm unlink` from repository root\n\n### Publish\n\n```bash\nnpm login\nnpm publish --access public\n```\n\n资料来源：[CLAUDE.md:1-40]()\n\n## Example Usage\n\n### Natural Language Examples\n\n| Instruction | Operations |\n|-------------|------------|\n| Comment \"Hello MCP\" on page \"Getting started\" | `search` → `create-a-comment` |\n| Add a page titled \"Notion MCP\" to page \"Development\" | `search` → `create-a-page` |\n| Get the content of page `1a6b35e6e67f802fa7e1d27686f017f2` | `retrieve-a-block-children` |\n\nThe AI will automatically plan the correct sequence of API calls to accomplish the task.\n\n资料来源：[README.md:1-20]()\n\n## Parameter Handling\n\nThe MCP proxy automatically deserializes JSON-string parameters to support nested objects and arrays:\n\n```mermaid\ngraph LR\n A[\"String: '{\\\"key\\\":\\\"value\\\"}'\"] --> B[\"deserializeParams()\"]\n B --> C[\"Object: {key: 'value'}\"]\n \n D[\"Array: ['[1,2,3]']\"] --> B\n B --> E[\"Array: [1, 2, 3]\"]\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:1-60]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| \"No base URL found\" | Ensure OpenAPI spec has a valid server URL |\n| Authentication errors | Verify `NOTION_TOKEN` is set correctly |\n| Page access denied | Connect the integration to the target page in Notion |\n| Port already in use | Use `--port` to specify a different port |\n\n### Node.js Version\n\nThe server requires Node.js 18+ for native `Headers` class support. A polyfill is available for older versions.\n\n资料来源：[src/openapi-mcp-server/client/polyfill-headers.ts:1-5]()\n\n## Next Steps\n\n- Review the [CLAUDE.md](CLAUDE.md) for architecture details\n- Explore the [OpenAPI specification](scripts/notion-openapi.json) for all available endpoints\n- Check the [repository issues](https://github.com/makenotion/notion-mcp-server/issues) for known limitations\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Transport Layers](#page-transport-layers), [MCP Proxy Implementation](#page-mcp-proxy), [Available MCP Tools](#page-available-tools)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/openapi-mcp-server/index.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/index.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/auth/index.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/index.ts)\n- [src/openapi-mcp-server/auth/types.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/types.ts)\n- [src/openapi-mcp-server/auth/template.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/template.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n
\n\n# System Architecture\n\n## Overview\n\nThe Notion MCP Server is an official Model Context Protocol (MCP) server implementation that exposes the Notion API as MCP tools. The server automatically generates MCP tools from an OpenAPI 3.1.0 specification, enabling AI assistants to interact with Notion workspaces through standardized MCP protocols.\n\n资料来源：[CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n## High-Level Architecture\n\nThe system follows a layered architecture where the OpenAPI specification serves as the single source of truth for tool definitions. Tools are auto-generated from the spec without requiring manual code changes for new endpoints.\n\n```mermaid\ngraph TD\n A[scripts/notion-openapi.json
OpenAPI 3.1.0 Spec] --> B[OpenAPIToMCPConverter]\n B --> C[MCPProxy]\n C --> D[MCP SDK]\n A --> E[HttpClient]\n E --> F[Notion API v1]\n \n B -.->|Converts to| G[MCPTools]\n C -.->|Registers| G\n```\n\n资料来源：[CLAUDE.md:4-10](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n## Core Components\n\n### Component Architecture Table\n\n| Component | File Path | Responsibility |\n|-----------|-----------|----------------|\n| OpenAPI Specification | `scripts/notion-openapi.json` | Single source of truth for all API endpoints and schemas |\n| Server Entry Point | `src/init-server.ts` | Loads spec, creates MCPProxy instance |\n| OpenAPI Parser | `src/openapi-mcp-server/openapi/parser.ts` | Converts OpenAPI → MCP tool definitions |\n| MCP Proxy | `src/openapi-mcp-server/mcp/proxy.ts` | Tool registration and request handling |\n| HTTP Client | `src/openapi-mcp-server/client/http-client.ts` | Executes Notion API calls |\n| Auth Module | `src/openapi-mcp-server/auth/` | Authentication and header management |\n| Server CLI | `scripts/start-server.ts` | Transport layer initialization |\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts) \n资料来源：[src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n\n### OpenAPI to MCP Converter\n\nThe `OpenAPIToMCPConverter` class in `parser.ts` handles the transformation of OpenAPI operations into MCP-compatible tool definitions.\n\n```typescript\nconvertToMCPTools(): {\n tools: Record\n openApiLookup: Record\n zip: Record\n}\n```\n\nThe conversion process:\n\n1. Iterates all paths and operations from the OpenAPI spec\n2. Extracts operation parameters and requestBody schemas\n3. Generates JSON Schema for input validation\n4. Extracts response schemas for return types\n5. Creates MCP tool definitions with operationId as tool name\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:75-150](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n\n### MCP Proxy\n\nThe `MCPProxy` class manages tool registration and execution through the MCP SDK:\n\n```typescript\nclass MCPProxy {\n constructor(openApiSpec: OpenAPIV3.Document)\n private setupHandlers(): void\n private truncateToolName(name: string): string\n private operationIdToTitle(operationId: string): string\n}\n```\n\nKey responsibilities:\n\n- **Tool Registration**: Uses `ListToolsRequestSchema` to expose available tools\n- **Tool Execution**: Uses `CallToolRequestSchema` to handle tool invocations\n- **Parameter Deserialization**: Handles JSON string parsing for complex parameters\n- **Annotation**: Marks tools with `readOnlyHint` or `destructiveHint` based on HTTP method\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:60-120](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n\n## HTTP Client Architecture\n\n### Request Execution Flow\n\n```mermaid\ngraph LR\n A[Tool Request] --> B[MCPProxy]\n B --> C[Parameter Processing]\n C --> D[Path/Query Separation]\n D --> E[HttpClient.operationFn]\n E --> F[Axios HTTP Call]\n F --> G[Notion API]\n G --> F\n F --> H[Response Headers]\n H --> I[MCPToolResult]\n```\n\nThe HTTP client handles:\n\n| Responsibility | Implementation |\n|----------------|----------------|\n| Base URL Configuration | Configured via OpenAPI spec server definition |\n| Header Management | Merges auth headers with operation-specific headers |\n| Parameter Routing | Separates path/query params from body params |\n| Form Data Support | Detects and sets appropriate Content-Type headers |\n| Response Conversion | Transforms Axios headers to standard Headers object |\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:50-100](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n\n### Parameter Processing\n\n```typescript\n// Path and query parameters are extracted to urlParameters\nif (param.in === 'path' || param.in === 'query') {\n if (params[param.name] !== undefined) {\n urlParameters[param.name] = params[param.name]\n }\n}\n\n// Body parameters remain separate for request body\n// Form data uses multipart encoding\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:30-45](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n\n## Authentication System\n\n### Authentication Architecture\n\n```mermaid\ngraph TD\n A[Environment Variables] --> B[Auth Module]\n B --> C{Header Type}\n C -->|NOTION_TOKEN| D[Bearer Token]\n C -->|OPENAPI_MCP_HEADERS| E[Raw JSON Headers]\n D --> F[Authorization Header]\n E --> F\n F --> G[HttpClient Headers]\n```\n\n### Auth Module Structure\n\nThe authentication system is split into three modules:\n\n| Module | Purpose |\n|--------|---------|\n| `auth/types.ts` | TypeScript interfaces for auth configuration |\n| `auth/template.ts` | Header template definitions and validation |\n| `auth/index.ts` | Main export combining auth functionality |\n\n资料来源：[src/openapi-mcp-server/auth/index.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/index.ts) \n资料来源：[src/openapi-mcp-server/auth/types.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/types.ts)\n\n### Authentication Methods\n\nThe server supports two authentication approaches:\n\n| Method | Environment Variable | Format |\n|--------|---------------------|--------|\n| Simple Token | `NOTION_TOKEN` | `ntn_****` integration token |\n| Advanced Headers | `OPENAPI_MCP_HEADERS` | JSON with Authorization and Notion-Version |\n\n资料来源：[src/openapi-mcp-server/auth/template.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/template.ts)\n\n## Transport Layer Architecture\n\n### Supported Transports\n\n```mermaid\ngraph TD\n A[MCP Client] --> B{Transport Type}\n B -->|stdio| C[Standard I/O]\n B -->|http| D[Streamable HTTP]\n \n C --> E[scripts/start-server.ts]\n D --> E\n E --> F[MCPProxy]\n F --> G[Notion API]\n```\n\nThe server supports two transport mechanisms configured via CLI arguments:\n\n| Transport | Default | CLI Flag | Port |\n|-----------|---------|----------|------|\n| stdio | Yes | `--transport stdio` | N/A |\n| Streamable HTTP | No | `--transport http` | 3000 |\n\n资料来源：[scripts/start-server.ts:1-50](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n### HTTP Transport Security\n\nFor HTTP transport, bearer token authentication is required:\n\n```bash\n# Auto-generated token (development only)\nnpx @notionhq/notion-mcp-server --transport http\n\n# Custom token via CLI\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-token\"\n\n# Custom token via environment variable\nAUTH_TOKEN=\"your-token\" npx @notionhq/notion-mcp-server --transport http\n```\n\n资料来源：[scripts/start-server.ts:30-80](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Tool Naming Conventions\n\nTool names are derived from OpenAPI `operationId` with the following transformations:\n\n| Original operationId | Generated Tool Name |\n|---------------------|---------------------|\n| `retrieve-a-database` | `Retrieve-A-Database` |\n| `create-a-page` | `Create-A-Page` |\n| `search` | `Search` |\n\n**Rules:**\n- Names are truncated to 64 characters maximum\n- Converted to Title Case for display\n- Prefixed with parent tool name and hyphen when multiple methods exist\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:140-160](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n\n## Schema Conversion\n\n### OpenAPI to JSON Schema Mapping\n\nThe `convertOpenApiSchemaToJsonSchema` method handles complex schema transformations:\n\n| OpenAPI Feature | JSON Schema Output | Notes |\n|-----------------|-------------------|-------|\n| `format: binary` | `format: uri-reference` | For file path handling |\n| `type: object` | `type: object` | Includes properties and additionalProperties |\n| `type: array` | `type: array` | Converts items recursively |\n| `oneOf/anyOf/allOf` | `oneOf/anyOf/allOf` | Preserves discriminator info |\n| `enum` | `enum` | Preserves allowed values |\n| `const` | `const` | Important for discriminator keys |\n| `default` | `default` | Provides fallback values |\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:20-80](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n\n## Server Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant CLI as scripts/start-server.ts\n participant Init as src/init-server.ts\n participant Proxy as MCPProxy\n participant Auth as Auth Module\n \n CLI->>Init: Loads notion-openapi.json\n Init->>Auth: parseHeadersFromEnv()\n Auth-->>Init: Headers configuration\n Init->>Proxy: new MCPProxy(spec, headers)\n Proxy->>Proxy: convertToMCPTools()\n Proxy->>Proxy: setupHandlers()\n Init->>CLI: Configured server\n CLI->>CLI: Start transport (stdio/http)\n```\n\n资料来源：[src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n\n## API Version Management\n\nThe server uses Notion API version `2025-09-03` (Data Source Edition):\n\n| Endpoint Type | Pattern | Description |\n|---------------|---------|-------------|\n| Traditional | `/v1/databases/{database_id}` | Classic database operations |\n| Data Source | `/v1/data_sources/{data_source_id}` | New data source endpoints |\n\n资料来源：[CLAUDE.md:18-20](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n## Configuration Options\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `NOTION_TOKEN` | Yes (recommended) | Notion integration token |\n| `OPENAPI_MCP_HEADERS` | No | JSON string with custom headers |\n| `AUTH_TOKEN` | No | Bearer token for HTTP transport |\n| `PORT` | No | HTTP server port (default: 3000) |\n\n### CLI Arguments\n\n| Argument | Type | Default | Description |\n|----------|------|---------|-------------|\n| `--transport` | string | stdio | Transport type |\n| `--port` | number | 3000 | HTTP server port |\n| `--auth-token` | string | auto-generated | Bearer token |\n| `--disable-auth` | flag | false | Disable HTTP auth |\n| `--help` | flag | - | Show help message |\n\n资料来源：[scripts/start-server.ts:5-40](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n---\n\n\n\n## Transport Layers\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Authentication System](#page-authentication)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n
\n\n# Transport Layers\n\nThe Notion MCP Server supports two distinct transport mechanisms for communication between AI clients and the server: **stdio** (Standard Input/Output) and **Streamable HTTP**. These transport layers define how MCP protocol messages are exchanged, authentication is handled, and the server exposes its capabilities to clients.\n\n## Overview\n\nTransport layers in the MCP (Model Context Protocol) serve as the communication backbone between AI assistants and the server. The Notion MCP Server abstracts the underlying transport details, allowing clients to choose the mode that best fits their environment.\n\n```mermaid\ngraph TD\n subgraph \"Transport Modes\"\n A[\"stdio Transport
(Default)\"] \n B[\"Streamable HTTP Transport\"]\n end\n \n subgraph \"Client Types\"\n C[\"Cursor\"]\n D[\"Claude Desktop\"]\n E[\"Zed Editor\"]\n F[\"GitHub Copilot CLI\"]\n end\n \n A --> C\n A --> D\n B --> E\n B --> F\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Transport Types\n\n### stdio Transport (Default)\n\nThe stdio transport is the default mode for the Notion MCP Server. It uses standard input and output streams for communication, making it ideal for local development and integration with desktop AI clients.\n\n**Characteristics:**\n\n- Bidirectional JSON-RPC communication via stdin/stdout\n- No network binding required\n- Suitable for local MCP clients\n- Default mode when no transport is specified\n\n**Usage:**\n\n```bash\n# Default stdio mode\nnotion-mcp-server\n\n# Explicit stdio mode\nnotion-mcp-server --transport stdio\n```\n\n资料来源：[scripts/start-server.ts:1-45](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n### Streamable HTTP Transport\n\nThe HTTP transport enables network-based communication, allowing remote or distributed clients to connect to the MCP server. This mode requires explicit configuration and includes built-in bearer token authentication.\n\n**Characteristics:**\n\n- HTTP-based protocol over TCP/IP\n- Session-based communication with `mcp-session-id` header\n- Bearer token authentication (required unless disabled)\n- Runs on configurable port (default: 3000)\n- Endpoint available at `/mcp`\n\n**Basic Usage:**\n\n```bash\n# Default HTTP on port 3000\nnotion-mcp-server --transport http\n\n# Custom port\nnotion-mcp-server --transport http --port 8080\n\n# With custom auth token\nnotion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\n资料来源：[scripts/start-server.ts:1-50](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Command Line Options\n\nThe server accepts the following command line arguments to configure transport behavior:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--transport ` | string | `stdio` | Transport type: `stdio` or `http` |\n| `--port ` | integer | `3000` | HTTP server port (only for HTTP transport) |\n| `--auth-token ` | string | auto-generated | Bearer token for HTTP authentication |\n| `--disable-auth` | flag | `false` | Disable bearer token authentication |\n| `--help`, `-h` | flag | - | Display help message |\n\n**Precedence:** Command line arguments take precedence over environment variables.\n\n资料来源：[scripts/start-server.ts:10-35](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Authentication\n\n### Environment Variables\n\nThe server respects the following environment variables for authentication configuration:\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `NOTION_TOKEN` | Notion integration secret token | Yes (for API calls) |\n| `OPENAPI_MCP_HEADERS` | JSON string with custom headers | Alternative to NOTION_TOKEN |\n| `AUTH_TOKEN` | Bearer token for HTTP transport | For HTTP transport |\n\n**Header Format for OPENAPI_MCP_HEADERS:**\n\n```json\n{\n \"Authorization\": \"Bearer ntn_****\",\n \"Notion-Version\": \"2025-09-03\"\n}\n```\n\n### HTTP Transport Authentication Modes\n\n#### Auto-Generated Token (Development Only)\n\nWhen running without explicit authentication configuration, the server generates a secure random token:\n\n```bash\nnpx notion-mcp-server --transport http\n```\n\nOutput:\n```\nGenerated auth token: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\nUse this token in the Authorization header: Bearer a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\n```\n\n#### Custom Token via Command Line (Production)\n\n```bash\nnotion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\n#### Custom Token via Environment Variable\n\n```bash\nAUTH_TOKEN=\"your-secret-token\" notion-mcp-server --transport http\n```\n\n#### Disabling Authentication\n\n```bash\nnotion-mcp-server --transport http --disable-auth\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## HTTP Request Format\n\nWhen using the Streamable HTTP transport, all requests must include specific headers:\n\n### Required Headers\n\n| Header | Value | Description |\n|--------|-------|-------------|\n| `Authorization` | `Bearer ` | Bearer token for authentication |\n| `Content-Type` | `application/json` | Request content type |\n| `mcp-session-id` | `` | MCP session identifier |\n\n### Example Request\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n**Server Endpoint:** `http://0.0.0.0:/mcp`\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Architecture\n\n### Component Flow\n\n```mermaid\ngraph TD\n subgraph \"Entry Point\"\n A[\"scripts/start-server.ts
Parse CLI arguments\"]\n end\n \n subgraph \"Initialization\"\n B[\"src/init-server.ts
Load OpenAPI spec\"]\n C[\"Create MCPProxy instance\"]\n end\n \n subgraph \"Transport Layer\"\n D[\"Transport Selection
stdio vs http\"]\n end\n \n subgraph \"MCP Server\"\n E[\"MCPProxy.setupHandlers()
Register tools\"]\n F[\"OpenAPIToMCPConverter
Convert OpenAPI → MCP tools\"]\n end\n \n subgraph \"HTTP Client\"\n G[\"HttpClient
Execute Notion API calls\"]\n end\n \n A --> B\n B --> C\n C --> D\n D --> E\n E --> F\n F --> G\n \n style D fill:#f9f,stroke:#333\n```\n\n资料来源：[CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n### Request Processing Flow (HTTP Transport)\n\n```mermaid\nsequenceDiagram\n participant Client\n participant HTTPServer as HTTP Server
(Express)\n participant MCPServer as MCP Server
(MCPProxy)\n participant HTTPClient as HttpClient\n participant NotionAPI as Notion API\n \n Client->>HTTPServer: HTTP Request with Auth Header\n HTTPServer->>HTTPServer: Validate Bearer Token\n alt Token Valid\n HTTPServer->>MCPServer: Forward MCP Request\n MCPServer->>HTTPClient: Execute Tool Call\n HTTPClient->>NotionAPI: API Request\n NotionAPI-->>HTTPClient: API Response\n HTTPClient-->>MCPServer: Structured Response\n MCPServer-->>HTTPServer: MCP Response\n HTTPServer-->>Client: HTTP Response\n else Token Invalid\n HTTPServer-->>Client: 401 Unauthorized\n end\n```\n\n## Client Configuration Examples\n\n### Cursor & Claude Desktop\n\n**stdio Transport:**\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n**HTTP Transport:**\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\",\n \"AUTH_TOKEN\": \"your-auth-token\"\n }\n }\n }\n}\n```\n\n### Zed Editor\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\" }\"\n }\n },\n \"settings\": {}\n }\n }\n}\n```\n\n### GitHub Copilot CLI\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Docker Deployment\n\n### Option 1: Official Docker Hub Image\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN\",\n \"mcp/notion\"\n ],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### Option 2: Local Docker Build\n\n```bash\ndocker compose build\n```\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN=ntn_****\",\n \"notion-mcp-server\"\n ]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Local Development Testing\n\nFor testing changes locally in development environments:\n\n1. Run `npm link` from repository root to create a machine-global symlink\n2. Add configuration to client's `mcp.json`\n3. Run `npm unlink` for cleanup\n\n```bash\nnpm link\n```\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## HTTP Client Implementation\n\nThe internal HTTP client handles the actual API communication with Notion's backend:\n\n**Key Responsibilities:**\n\n- Base URL configuration from OpenAPI spec\n- Request header management\n- Form data handling for file uploads\n- Response header conversion to standard `Headers` object\n- URL parameter vs body parameter routing\n\n```typescript\n// Parameter routing logic\nif (param.in === 'path' || param.in === 'query') {\n urlParameters[param.name] = params[param.name]\n}\n\n// Body parameters for POST/PUT requests\nif (!operation.requestBody && !formData) {\n urlParameters[key] = bodyParams[key]\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-50](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n\n## Choosing a Transport\n\n| Use Case | Recommended Transport | Reason |\n|----------|----------------------|--------|\n| Local desktop AI client | stdio | Simple, no network required |\n| Remote/distributed clients | HTTP | Network accessible |\n| Development/testing | stdio or HTTP (auto-token) | Flexibility |\n| Production deployment | HTTP with custom token | Security and scalability |\n| Docker containers | HTTP | Container networking |\n| CI/CD pipelines | stdio | Ephemeral execution |\n\n## Summary\n\nThe Notion MCP Server provides two transport mechanisms optimized for different deployment scenarios. The **stdio transport** offers simplicity for local use, while the **Streamable HTTP transport** enables networked deployments with built-in authentication. Both transports leverage the same underlying MCP tool registration and HTTP client infrastructure, ensuring consistent behavior regardless of the communication method chosen.\n\n---\n\n\n\n## MCP Proxy Implementation\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Available MCP Tools](#page-available-tools)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n
\n\n# MCP Proxy Implementation\n\n## Overview\n\nThe MCP Proxy is the core component of the Notion MCP Server that bridges the gap between the Notion OpenAPI specification and the Model Context Protocol (MCP). It transforms REST API endpoints defined in the OpenAPI spec into executable MCP tools that AI assistants can invoke.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[OpenAPI Spec
scripts/notion-openapi.json] --> B[OpenAPIToMCPConverter]\n B --> C[MCP Tools Generation]\n C --> D[MCPProxy]\n D --> E[MCP SDK Server]\n \n F[HTTP Client] --> G[Notion API]\n D --> F\n \n H[MCP Client
Claude/Cursor] --> E\n E --> H\n \n I[Tool Call Request] --> E\n E --> F\n F --> G\n G --> J[API Response]\n J --> E\n E --> K[Tool Result]\n K --> H\n```\n\n## Core Components\n\n### MCPProxy Class\n\nThe `MCPProxy` class serves as the central orchestration layer. It initializes the MCP server, converts OpenAPI specifications into MCP tools, and handles all tool execution requests.\n\n**File Location:** `src/openapi-mcp-server/mcp/proxy.ts`\n\n#### Constructor Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `name` | `string` | Display name for the MCP server |\n| `openApiSpec` | `OpenAPIV3.Document` | Parsed OpenAPI 3.1.0 specification |\n| `baseUrl` | `string \\| undefined` | Optional base URL override |\n| `openApiSpecPath` | `string` | Path to the OpenAPI spec file |\n\n#### Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant MCPProxy\n participant Converter\n participant HttpClient\n participant MCPSDK\n\n Client->>MCPProxy: new MCPProxy(name, spec)\n MCPProxy->>HttpClient: Create HttpClient instance\n MCPProxy->>Converter: Create OpenAPIToMCPConverter\n Converter->>Converter: convertToMCPTools()\n Converter-->>MCPProxy: tools, openApiLookup\n MCPProxy->>MCPSDK: setupHandlers()\n MCPSDK-->>Client: Server ready\n```\n\n### Tool Registration\n\nThe `setupHandlers()` method registers two primary request handlers with the MCP SDK:\n\n#### ListToolsRequestHandler\n\nReturns all available MCP tools to clients. For each operation in the OpenAPI spec:\n\n1. Iterates through all tools and their methods\n2. Constructs tool names using pattern: `{toolName}-{methodName}`\n3. Truncates names to 64 characters for MCP compliance\n4. Determines read/write behavior based on HTTP method\n\n**Tool Naming Convention:**\n\n```typescript\nconst toolNameWithMethod = `${toolName}-${method.name}`;\nconst truncatedToolName = this.truncateToolName(toolNameWithMethod);\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:52-66]()\n\n#### CallToolRequestHandler\n\nProcesses incoming tool execution requests:\n\n1. Extracts tool name from request\n2. Looks up operation in `openApiLookup` map\n3. Executes HTTP request via `HttpClient`\n4. Returns formatted response to MCP client\n\n### Tool Annotations\n\nEach tool includes metadata annotations:\n\n| Annotation | Type | Description |\n|------------|------|-------------|\n| `title` | `string` | Human-readable operation title |\n| `readOnlyHint` | `boolean` | `true` for GET requests |\n| `destructiveHint` | `boolean` | `true` for non-GET requests |\n\n```typescript\nannotations: {\n title: this.operationIdToTitle(method.name),\n ...(isReadOnly\n ? { readOnlyHint: true }\n : { destructiveHint: true }),\n},\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:60-67]()\n\n## HTTP Client Integration\n\nThe `HttpClient` class handles all outbound HTTP communication with the Notion API.\n\n### Configuration\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `baseUrl` | `string` | Notion API base URL |\n| `headers` | `Record` | Default request headers |\n\n### Request Processing\n\n1. **Parameter Extraction**: Separates path, query, and body parameters\n2. **Form Data Handling**: Detects `multipart/form-data` content types\n3. **Header Management**: Sets appropriate Content-Type headers\n4. **Response Conversion**: Transforms axios responses to standard Headers objects\n\n```typescript\nconst hasBody = Object.keys(bodyParams).length > 0\nconst headers = formData\n ? formData.getHeaders()\n : { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:70-76]()\n\n## OpenAPI to MCP Conversion\n\nThe `OpenAPIToMCPConverter` class transforms OpenAPI operations into MCP tool definitions.\n\n### Schema Conversion\n\nThe converter handles:\n\n- **Object types**: Properties, required fields, additionalProperties\n- **Binary formats**: Converts to URI-reference format for file handling\n- **Enumerations**: Preserves enum values\n- **Const values**: Supports oneOf discriminators\n- **Default values**: Includes default values in schemas\n\n### JSON Schema Mapping\n\n| OpenAPI Type | JSON Schema Type |\n|--------------|------------------|\n| `object` | `object` |\n| `array` | `array` |\n| `string` | `string` |\n| `integer` | `integer` |\n| `number` | `number` |\n| `boolean` | `boolean` |\n| `binary` | `uri-reference` |\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:45-72]()\n\n## Server Initialization\n\n### Entry Point\n\nThe server is initialized via `src/init-server.ts`:\n\n```mermaid\ngraph LR\n A[scripts/start-server.ts] --> B[src/init-server.ts]\n B --> C[loadOpenApiSpec]\n C --> D[Validate JSON Schema]\n D --> E[new MCPProxy]\n E --> F[Return proxy instance]\n```\n\n### Specification Loading\n\n1. Reads OpenAPI spec from filesystem\n2. Parses JSON content\n3. Overrides `baseUrl` if specified\n4. Validates against OpenAPI 3.1.0 schema\n\n```typescript\nexport async function initProxy(specPath: string, baseUrl: string | undefined) {\n const openApiSpec = await loadOpenApiSpec(specPath, baseUrl)\n const proxy = new MCPProxy('Notion API', openApiSpec)\n return proxy\n}\n```\n\n资料来源：[src/init-server.ts:43-48]()\n\n## Command Line Interface\n\nThe CLI entry point supports multiple transport modes and authentication options.\n\n### Supported Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--transport` | `stdio` \\| `http` | `stdio` | Transport type |\n| `--port` | `number` | `3000` | HTTP server port |\n| `--auth-token` | `string` | auto-generated | Bearer token for HTTP auth |\n| `--disable-auth` | `flag` | `false` | Disable authentication |\n| `--help`, `-h` | `flag` | - | Show help message |\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `NOTION_TOKEN` | Notion integration token |\n| `OPENAPI_MCP_HEADERS` | JSON string with API headers |\n| `AUTH_TOKEN` | Bearer token for HTTP transport |\n\n资料来源：[scripts/start-server.ts:1-30]()\n\n## Tool Execution Workflow\n\n```mermaid\nsequenceDiagram\n participant AI as AI Assistant\n participant MCPSDK as MCP SDK\n participant Proxy as MCPProxy\n participant Client as HttpClient\n participant API as Notion API\n\n AI->>MCPSDK: list_tools()\n MCPSDK-->>AI: Available tools\n \n AI->>MCPSDK: call_tool(\"retrieve-page-123\")\n MCPSDK->>Proxy: execute(toolName, params)\n \n alt Tool Lookup\n Proxy->>Proxy: openApiLookup[toolName]\n Proxy-->>Proxy: Operation found\n end\n \n Proxy->>Client: execute(operationId, params)\n \n Client->>API: HTTP Request\n API-->>Client: API Response\n \n Client-->>Proxy: Formatted response\n Proxy-->>MCPSDK: Tool result\n MCPSDK-->>AI: Success/Error\n```\n\n## Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@modelcontextprotocol/sdk` | `^1.25.1` | MCP protocol implementation |\n| `axios` | `^1.8.4` | HTTP client |\n| `express` | `^4.21.2` | HTTP server transport |\n| `openapi-client-axios` | `^7.5.5` | OpenAPI client generation |\n| `zod` | `3.24.1` | Schema validation |\n\n资料来源：[package.json:22-40]()\n\n## Key Implementation Patterns\n\n### Tool Name Transformation\n\nTool names are generated from OpenAPI `operationId` values:\n\n1. **Original**: `retrieve-a-database`\n2. **Transformation**: Convert to title case → `RetrieveADatabase`\n3. **Truncation**: Limit to 64 characters\n\n### Request Body Handling\n\n```typescript\n// If no requestBody defined, promote body params to query params\nif (!operation.requestBody && !formData) {\n for (const key in bodyParams) {\n if (bodyParams[key] !== undefined) {\n urlParameters[key] = bodyParams[key]\n delete bodyParams[key]\n }\n }\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:50-56]()\n\n### Header Parsing\n\nHeaders can be configured via the `OPENAPI_MCP_HEADERS` environment variable:\n\n```typescript\nprivate parseHeadersFromEnv(): Record {\n const headersStr = process.env.OPENAPI_MCP_HEADERS\n if (headersStr) {\n try {\n return JSON.parse(headersStr)\n } catch {\n console.error('Failed to parse OPENAPI_MCP_HEADERS')\n }\n }\n return {}\n}\n```\n\n## Error Handling\n\nThe proxy implements robust error handling at multiple levels:\n\n| Error Type | Handling |\n|------------|----------|\n| Invalid operation | `Error: Operation {id} not found` |\n| HTTP errors | Propagated from axios |\n| JSON parse errors | Console error + process exit |\n| Spec validation | `ValidationError` with details |\n\n## Performance Considerations\n\n1. **Tool Lookup**: O(1) lookup via `openApiLookup` Map\n2. **Lazy Loading**: Operations are loaded once at initialization\n3. **Connection Pooling**: Axios manages HTTP connection reuse\n4. **Schema Caching**: Resolved references cached in memory\n\n---\n\n\n\n## Available MCP Tools\n\n### 相关页面\n\n相关主题：[Data Sources (v2.0.0 Breaking Changes)](#page-data-sources-v2), [System Architecture](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/notion-openapi.json](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/notion-openapi.json)\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n
\n\n# Available MCP Tools\n\n## Overview\n\nThe Notion MCP Server exposes the Notion API as MCP (Model Context Protocol) tools, enabling AI clients to interact with Notion workspaces programmatically. Each tool corresponds to a specific Notion API endpoint and is auto-generated from the OpenAPI specification at `scripts/notion-openapi.json` 资料来源：[CLAUDE.md:1-12]()\n\nThe MCP tools serve as the bridge between AI assistants and Notion's API, providing capabilities to:\n\n- Search and retrieve pages and databases\n- Create, update, and manage content\n- Work with comments and user information\n- Query data sources with filters and sorting\n\n## Architecture\n\nThe tool generation and execution follows a clear architectural flow:\n\n```mermaid\ngraph TD\n A[scripts/notion-openapi.json
OpenAPI 3.1.0 Spec] --> B[OpenAPIToMCPConverter]\n B --> C[MCP Tools Registry]\n C --> D[AI Client]\n D --> E[Tool Invocation]\n E --> F[deserializeParams]\n F --> G[HttpClient.executeOperation]\n G --> H[Notion API]\n \n subgraph \"src/openapi-mcp-server/\"\n B\n F\n G\n end\n```\n\n### Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| OpenAPI Spec | `scripts/notion-openapi.json` | Source of truth for all tools |\n| Parser | `src/openapi-mcp-server/openapi/parser.ts` | Converts OpenAPI to MCP tools |\n| Proxy | `src/openapi-mcp-server/mcp/proxy.ts` | Registers tools with MCP SDK |\n| HTTP Client | `src/openapi-mcp-server/client/http-client.ts` | Executes API calls |\n\n资料来源：[CLAUDE.md:15-22]()\n\n## Tool Generation Flow\n\nThe tool generation process consists of five steps:\n\n1. **`OpenAPIToMCPConverter.convertToMCPTools()`** iterates over all paths and operations in the OpenAPI spec\n2. Each operation becomes an MCP tool with name derived from `operationId`\n3. Parameters and requestBody are converted to `inputSchema`\n4. Response schema becomes `returnSchema`\n5. **`MCPProxy.setupHandlers()`** registers tools with the MCP SDK\n\n```mermaid\nsequenceDiagram\n participant Spec as OpenAPI Spec\n participant Parser as OpenAPIToMCPConverter\n participant Proxy as MCPProxy\n participant SDK as MCP SDK\n participant Client as AI Client\n \n Spec->>Parser: Load specification\n Parser->>Parser: convertToMCPTools()\n Parser->>Proxy: tools, openApiLookup\n Proxy->>SDK: registerToolHandlers()\n Client->>SDK: list_tools\n SDK->>Client: Available tools\n Client->>SDK: call_tool\n SDK->>Proxy: executeOperation\n```\n\n资料来源：[CLAUDE.md:24-31]()\n\n## Version 2.0.0 Breaking Changes\n\n**Version 2.0.0 migrates to the Notion API 2025-09-03** which introduces data sources as the primary abstraction for databases 资料来源：[README.md:1-50]()\n\n### Removed Tools (3)\n\n| Old Tool | Replacement |\n|----------|-------------|\n| `post-database-query` | `query-data-source` |\n| `update-a-database` | `update-a-data-source` |\n| `create-a-database` | `create-a-data-source` |\n\n### New Tools (7)\n\n| New Tool | Purpose |\n|----------|---------|\n| `query-data-source` | Query a data source (database) with filters and sorts |\n| `retrieve-a-data-source` | Get metadata and schema for a data source |\n| `update-a-data-source` | Update data source properties |\n| `create-a-data-source` | Create a new data source |\n| `list-data-source-templates` | List available templates in a data source |\n| `move-page` | Move a page to a different parent location |\n| `retrieve-a-database` | Get database metadata including its data source IDs |\n\n### Parameter Changes\n\n| Change Type | Old Parameter | New Parameter |\n|-------------|---------------|---------------|\n| Database ID | `database_id` | `data_source_id` |\n| Search Filter | `[\"page\", \"database\"]` | `[\"page\", \"data_source\"]` |\n\n资料来源：[README.md:1-50]()\n\n## Tool Naming Conventions\n\nTool names are derived directly from the OpenAPI `operationId`:\n\n- Example: `retrieve-a-database` becomes `RetrieveADatabase`\n- Names are truncated to 64 characters maximum\n- Converted to title case for display purposes\n\n```typescript\n// operationId: \"retrieve-a-database\"\n// Resulting tool name: \"RetrieveADatabase\"\nprivate operationIdToTitle(operationId: string): string {\n return operationId\n .split('-')\n .map(word => word.charAt(0).toUpperCase() + word.slice(1))\n .join('')\n .slice(0, 64);\n}\n```\n\n资料来源：[CLAUDE.md:33-34]()\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `NOTION_TOKEN` | Notion integration token (recommended) | Yes |\n| `OPENAPI_MCP_HEADERS` | JSON string with Notion API headers | Alternative |\n| `AUTH_TOKEN` | Bearer token for HTTP transport authentication | Optional |\n| `OPENAPI_MCP_HEADERS` | Custom headers for Notion API requests | Optional |\n\n资料来源：[README.md:1-50]()\n\n### Header Configuration Example\n\n```json\n{\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\"}\"\n}\n```\n\n## Parameter Handling\n\n### Deserialization Process\n\nThe MCP server handles a known issue with double-serialized JSON parameters (GitHub issue #176). When parameters arrive as stringified JSON objects or arrays, they are automatically deserialized:\n\n```typescript\nfunction deserializeParams(params: Record): Record {\n for (const [key, value] of Object.entries(params)) {\n if (typeof value === 'string') {\n const trimmed = value.trim();\n if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||\n (trimmed.startsWith('[') && trimmed.endsWith(']'))) {\n try {\n const parsed = JSON.parse(value);\n if (typeof parsed === 'object' && parsed !== null) {\n result[key] = Array.isArray(parsed)\n ? parsed\n : deserializeParams(parsed);\n }\n } catch { /* keep original string */ }\n }\n }\n }\n return result;\n}\n```\n\nThis function recursively processes nested objects and arrays to ensure proper parameter handling 资料来源：[src/openapi-mcp-server/mcp/proxy.ts:1-50]()\n\n### Schema Conversion\n\nThe `OpenAPIToMCPConverter` converts OpenAPI schemas to JSON Schema format for MCP tool definitions:\n\n- `type: string` with `format: binary` → converted to `format: uri-reference`\n- Handles `oneOf`, `anyOf`, `allOf` schema composition\n- Preserves `enum` values and `const` discriminators\n- Maintains `required` field arrays\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:1-50]()\n\n## Example Usage\n\n### Search and Create\n\n```text\nComment \"Hello MCP\" on page \"Getting started\"\n```\n\nThe AI correctly plans two API calls:\n1. `v1/search` - Find the page \"Getting started\"\n2. `v1/comments` - Create the comment\n\n### Page Creation\n\n```text\nAdd a page titled \"Notion MCP\" to page \"Development\"\n```\n\n### Direct ID Reference\n\n```text\nGet the content of page 1a6b35e6e67f802fa7e1d27686f017f2\n```\n\n资料来源：[README.md:1-50]()\n\n## MCP Client Configuration\n\n### Cursor & Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### Zed\n\n```json\n{\n \"context_servers\": {\n \"notion-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"]\n },\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\"}\"\n }\n }\n }\n}\n```\n\n### GitHub Copilot CLI\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:1-50]()\n\n## HTTP Transport Authentication\n\nWhen using Streamable HTTP transport, bearer token authentication is required:\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\n### Authentication Options\n\n| Method | Priority | Use Case |\n|--------|----------|----------|\n| `--auth-token` CLI arg | Highest | Production |\n| `AUTH_TOKEN` env var | Medium | Production |\n| Auto-generated token | Lowest | Development only |\n\nAll requests must include the bearer token:\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n资料来源：[README.md:1-50]()\n\n## Error Handling\n\nThe MCP server provides structured error responses for HTTP errors:\n\n```typescript\nif (error instanceof HttpClientError) {\n const data = error.data?.response?.data ?? error.data ?? {};\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({ error: data }),\n },\n ],\n isError: true,\n };\n}\n```\n\nErrors are logged to console with descriptive messages for debugging 资料来源：[src/openapi-mcp-server/mcp/proxy.ts:100-130]()\n\n## Adding New Tools\n\nTo add new tools, only modify the OpenAPI specification at `scripts/notion-openapi.json`. No code changes are required elsewhere—tools are automatically generated from the spec when the server starts 资料来源：[CLAUDE.md:18-22]()\n\n### OpenAPI Specification\n\nThe server uses OpenAPI 3.1.0 specification with both traditional and new data source endpoints:\n\n| Endpoint Type | Path Pattern |\n|--------------|--------------|\n| Traditional | `/v1/databases/{database_id}` |\n| Data Source | `/v1/data_sources/{data_source_id}` |\n\n资料来源：[CLAUDE.md:44-47]()\n\n## Development\n\n### Build & Test Commands\n\n```bash\nnpm run build # TypeScript compilation + CLI bundling\nnpm test # Run vitest tests\nnpm run dev # Start dev server with hot reload\n```\n\n### Local Testing\n\n1. Run `npm link` from repository root to create a machine-global symlink\n2. Update your MCP client's configuration:\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n3. Cleanup with `npm unlink` when done\n\n资料来源：[README.md:1-50]()\n\n---\n\n\n\n## Data Sources (v2.0.0 Breaking Changes)\n\n### 相关页面\n\n相关主题：[Available MCP Tools](#page-available-tools)\n\n
\nRelated Source Files\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n
\n\n# Data Sources (v2.0.0 Breaking Changes)\n\n## Overview\n\nVersion 2.0.0 of the Notion MCP Server introduces a fundamental architectural change by migrating to the **Notion API 2025-09-03**, which adopts **Data Sources** as the primary abstraction for databases. This represents a significant shift in how the MCP server interacts with Notion's database functionality.\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## What Are Data Sources?\n\nData Sources serve as a new abstraction layer that wraps traditional Notion databases. They provide enhanced metadata and schema capabilities that align with Notion's evolving platform architecture. The data source model maintains compatibility with existing database endpoints while introducing new functionality.\n\n资料来源：[CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\nThe Notion API 2025-09-03 version includes dual endpoint support:\n\n| Endpoint Type | Path Pattern | Purpose |\n|---------------|--------------|---------|\n| Traditional Database | `/v1/databases/{database_id}` | Legacy database operations |\n| New Data Source | `/v1/data_sources/{data_source_id}` | Modern data source operations |\n\n资料来源：[CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n## Breaking Changes Summary\n\n### Tools Removed\n\nThe following three tools have been **removed** and replaced by their data source equivalents:\n\n| Removed Tool | Replacement Tool | Purpose |\n|--------------|------------------|---------|\n| `post-database-query` | `query-data-source` | Query data source with filters and sorts |\n| `update-a-database` | `update-a-data-source` | Update data source properties |\n| `create-a-database` | `create-a-data-source` | Create a new data source |\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### New Tools Added\n\nSeven new tools have been introduced in version 2.0.0:\n\n| New Tool | Description |\n|----------|-------------|\n| `query-data-source` | Query a data source (database) with filters and sorts |\n| `retrieve-a-data-source` | Get metadata and schema for a data source |\n| `update-a-data-source` | Update data source properties |\n| `create-a-data-source` | Create a new data source |\n| `list-data-source-templates` | List available templates in a data source |\n| `move-page` | Move a page to a different parent location |\n| `retrieve-a-database` | Get database metadata including its data source IDs |\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Parameter Changes\n\n### Identifier Renaming\n\nAll database operations now use `data_source_id` instead of `database_id`:\n\n```typescript\n// Before (v1.x)\nparameters: {\n database_id: string;\n}\n\n// After (v2.0.0)\nparameters: {\n data_source_id: string;\n}\n```\n\n### Search Filter Values\n\nThe search operation filter values have been updated:\n\n| Previous Value | New Value |\n|----------------|-----------|\n| `\"database\"` | `\"data_source\"` |\n\n```typescript\n// Before (v1.x)\nfilter: {\n value: [\"page\", \"database\"];\n}\n\n// After (v2.0.0)\nfilter: {\n value: [\"page\", \"data_source\"];\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Page Creation Enhancement\n\nPage creation now supports both `page_id` and `database_id` parents for data sources:\n\n```typescript\ninterface CreatePageParameters {\n parent: {\n page_id?: string;\n database_id?: string; // Now includes database_id support\n };\n}\n```\n\n## Architecture Flow\n\n```mermaid\ngraph TD\n A[MCP Client Request] --> B[MCP Server]\n B --> C{Determine Operation Type}\n \n C -->|Database Operation| D[Database Endpoints]\n C -->|Data Source Operation| E[Data Source Endpoints]\n \n D --> F[/v1/databases/{database_id}]\n E --> G[/v1/data_sources/{data_source_id}]\n \n F --> H[Notion API 2025-09-03]\n G --> H\n \n H --> I[Response with Schema]\n I --> J[OpenAPI Parser]\n J --> K[MCP Tool Response]\n```\n\n## Migration Guide\n\n### Do I Need to Migrate?\n\n**No code changes required.** MCP tools are discovered automatically when the server starts. When you upgrade to v2.0.0, AI clients will automatically see the new tools.\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Automatic Discovery\n\nThe MCP server auto-generates tools from the OpenAPI specification located at `scripts/notion-openapi.json`. Tool generation follows this flow:\n\n```mermaid\ngraph LR\n A[scripts/notion-openapi.json] --> B[OpenAPIToMCPConverter]\n B --> C[convertToMCPTools]\n C --> D[MCP Tools Registry]\n D --> E[MCPProxy.setupHandlers]\n E --> F[MCP SDK]\n```\n\n资料来源：[CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n### Tool Naming Conventions\n\nTool names derive from the OpenAPI `operationId` field:\n\n| OpenAPI operationId | MCP Tool Name |\n|---------------------|---------------|\n| `query-data-source` | `query-data-source` |\n| `retrieve-a-data-source` | `retrieve-a-data-source` |\n| `update-a-data-source` | `update-a-data-source` |\n\nNames are truncated to 64 characters and converted to title case for display purposes.\n\n## OpenAPI Schema Conversion\n\nThe parser converts OpenAPI schemas to JSON Schema format for MCP tool definitions. The `convertOpenApiSchemaToJsonSchema` method handles complex type conversions:\n\n```typescript\n// Handles the following conversions:\n// - binary format → uri-reference format\n// - oneOf/anyOf/allOf → proper JSON Schema composition\n// - const values for discriminators\n// - default values preservation\n```\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n\n### Response Schema Handling\n\nThe `extractResponseType` method processes API responses:\n\n1. Looks for success responses (200, 201, 202, 204)\n2. Extracts JSON schema from `application/json` content type\n3. Preserves response descriptions\n4. Falls back to generic formats for non-JSON responses\n\n```typescript\nprivate extractResponseType(responses: OpenAPIV3.ResponsesObject | undefined): IJsonSchema | null\n```\n\n## HTTP Client Architecture\n\nThe HTTP client handles parameter serialization and request execution:\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Client\n participant Proxy as MCPProxy\n participant Client as HttpClient\n participant Notion as Notion API\n \n MCP->>Proxy: Call Tool\n Proxy->>Client: Execute with params\n Client->>Client: Deserialize JSON strings\n Client->>Notion: API Request\n Notion-->>Client: Response\n Client-->>Proxy: Formatted Result\n Proxy-->>MCP: Tool Response\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n\n### Parameter Deserialization\n\nThe `deserializeParams` function recursively processes incoming parameters to convert JSON-like strings into actual objects:\n\n```typescript\nfunction deserializeParams(params: Record): Record\n```\n\nThis handles:\n- JSON object strings → parsed objects\n- JSON array strings → parsed arrays\n- Nested object deserialization\n- Array item deserialization\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n\n## API Version Configuration\n\nThe server uses the Notion API version `2025-09-03` (Data Source Edition):\n\n```bash\n# Via environment variable\nNOTION_TOKEN=ntn_****\n\n# Or via OPENAPI_MCP_HEADERS\nOPENAPI_MCP_HEADERS='{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\"}'\n```\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Configuration Options\n\n### Transport Modes\n\n| Transport | Default | Description |\n|-----------|---------|-------------|\n| `stdio` | Yes | Standard I/O transport |\n| `http` | No | Streamable HTTP transport |\n\n### HTTP Transport Authentication\n\n```bash\n# Using command line\nnotion-mcp-server --transport http --port 3000 --auth-token your-token\n\n# Or via environment variable\nAUTH_TOKEN=your-token notion-mcp-server --transport http\n```\n\nThe `--auth-token` command line argument takes precedence over the `AUTH_TOKEN` environment variable.\n\n## Build and Deployment\n\n### Version Information\n\n| Property | Value |\n|----------|-------|\n| Package Name | `@notionhq/notion-mcp-server` |\n| Version | 2.3.0 |\n| License | MIT |\n\n### Build Commands\n\n```bash\nnpm run build # TypeScript compilation + CLI bundling\nnpm test # Run vitest tests\nnpm run dev # Start dev server with hot reload\n```\n\n### Docker Deployment\n\n```bash\n# Build locally\ndocker compose build\n\n# Run with NOTION_TOKEN\ndocker run --rm -i -e NOTION_TOKEN=ntn_**** notion-mcp-server\n```\n\n## Key Dependencies\n\n| Dependency | Version | Purpose |\n|------------|---------|---------|\n| `@modelcontextprotocol/sdk` | ^1.25.1 | MCP protocol implementation |\n| `axios` | ^1.8.4 | HTTP client |\n| `openapi-client-axios` | ^7.5.5 | OpenAPI client |\n| `zod` | 3.24.1 | Schema validation |\n\n## See Also\n\n- [Notion MCP Server Repository](https://github.com/makenotion/notion-mcp-server)\n- [MCP Protocol Specification](https://spec.modelcontextprotocol.io/)\n- [Notion API Documentation](https://developers.notion.com/reference/intro)\n\n---\n\n\n\n## Authentication System\n\n### 相关页面\n\n相关主题：[Transport Layers](#page-transport-layers), [npm Installation and Configuration](#page-npm-installation)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n
\n\n# Authentication System\n\nThe Notion MCP Server implements a dual-layer authentication system that secures both the communication between MCP clients and the server, as well as the requests made to the Notion API.\n\n## Overview\n\nThe authentication system serves two distinct purposes:\n\n1. **Transport Authentication**: Secures client-to-server communication when using the Streamable HTTP transport\n2. **Notion API Authentication**: Authenticates requests to the Notion API using integration tokens\n\n```\n┌─────────────┐ Bearer Token Auth ┌──────────────────┐ Notion Token ┌─────────────┐\n│ MCP Client │ ◄──────────────────────────► │ MCP Server │ ◄───────────────────► │ Notion API │\n└─────────────┘ (HTTP Transport) └──────────────────┘ └─────────────┘\n```\n\n## Transport Authentication (HTTP)\n\nWhen running the server with `--transport http`, bearer token authentication is enforced to protect the MCP endpoint from unauthorized access.\n\n### Configuration Methods\n\n| Method | Priority | Description |\n|--------|----------|-------------|\n| `--auth-token` CLI flag | Highest | Passed directly via command line |\n| `AUTH_TOKEN` environment variable | Middle | Set in shell environment |\n| Auto-generated token | Fallback | Generated automatically if neither is provided |\n\n### Command Line Options\n\n```bash\n# Recommended: Custom token via command line\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n\n# Alternative: Token via environment variable\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq/notion-mcp-server --transport http\n\n# Development: Auto-generated token\nnpx @notionhq/notion-mcp-server --transport http\n\n# Disable authentication (NOT recommended for production)\nnpx @notionhq/notion-mcp-server --transport http --disable-auth\n```\n\n### Token Validation Flow\n\n```mermaid\ngraph TD\n A[HTTP Request to /mcp] --> B{Auth Disabled?}\n B -->|Yes| E[Process Request]\n B -->|No| C{Token Present?}\n C -->|No| F[Return 401 Unauthorized]\n C -->|Yes| G{Token Valid?}\n G -->|No| H[Return 403 Forbidden]\n G -->|Yes| E\n F --> I[Error: Missing bearer token]\n H --> J[Error: Invalid bearer token]\n```\n\n### Error Responses\n\nThe server returns standardized JSON-RPC error responses for authentication failures:\n\n**Missing Token (401)**\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"error\": {\n \"code\": -32001,\n \"message\": \"Unauthorized: Missing bearer token\"\n },\n \"id\": null\n}\n```\n\n**Invalid Token (403)**\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"error\": {\n \"code\": -32002,\n \"message\": \"Forbidden: Invalid bearer token\"\n },\n \"id\": null\n}\n```\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n### Health Endpoint Exception\n\nThe `/health` endpoint is accessible without authentication, allowing health checks without bearer token validation:\n\n```typescript\napp.get('/health', (req, res) => {\n res.status(200).json({\n status: 'healthy',\n timestamp: new Date().toISOString(),\n transport: 'http',\n port: options.port\n })\n})\n```\n\n资料来源：[scripts/start-server.ts:1-100](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Notion API Authentication\n\nThe server authenticates with the Notion API using integration tokens configured via environment variables.\n\n### Configuration Options\n\n| Environment Variable | Description | Recommended |\n|---------------------|-------------|-------------|\n| `NOTION_TOKEN` | Notion integration secret token (recommended) | ✅ |\n| `OPENAPI_MCP_HEADERS` | JSON string with custom headers including Authorization | Alternative |\n\n### Using NOTION_TOKEN (Recommended)\n\n```bash\nNOTION_TOKEN=ntn_**** npx @notionhq/notion-mcp-server\n```\n\n### Using OPENAPI_MCP_HEADERS (Advanced)\n\n```bash\nOPENAPI_MCP_HEADERS='{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\"}' \\\n npx @notionhq/notion-mcp-server\n```\n\n### Header Parsing\n\nThe server parses authentication headers from the environment variable:\n\n```typescript\nprivate parseHeadersFromEnv(): Record {\n const headers: Record = {}\n const headerConfig = process.env.OPENAPI_MCP_HEADERS\n if (headerConfig) {\n try {\n const parsed = JSON.parse(headerConfig)\n Object.assign(headers, parsed)\n } catch {\n // Invalid JSON, skip header parsing\n }\n }\n return headers\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-50](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n\n## Docker Deployment\n\n### Option 1: Using NOTION_TOKEN\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"NOTION_TOKEN\", \"notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### Option 2: Using OPENAPI_MCP_HEADERS\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"OPENAPI_MCP_HEADERS\", \"notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\":\\\"Bearer ntn_****\\\",\\\"Notion-Version\\\":\\\"2025-09-03\\\"}\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Client Configuration Examples\n\n### Cursor / Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### Zed\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\" }\"\n }\n },\n \"settings\": {}\n }\n }\n}\n```\n\n### GitHub Copilot CLI\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n## API Version Header\n\nThe server uses Notion API version `2025-09-03` (Data Source Edition) for all API requests:\n\n```typescript\nconst headers = {\n 'Authorization': `Bearer ${notionToken}`,\n 'Notion-Version': '2025-09-03'\n}\n```\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Making HTTP Requests\n\nAll requests to the Streamable HTTP transport must include the bearer token:\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n## Security Considerations\n\n| Concern | Mitigation |\n|---------|------------|\n| Token exposure in logs | Use `--auth-token` flag instead of environment variable when possible |\n| Plaintext token transmission | Always use HTTPS in production deployments |\n| Token rotation | Support multiple configuration methods for easy rotation |\n| Unauthorized access | Bearer token required by default for HTTP transport |\n\n## Integration Token Setup\n\nBefore using the server, ensure your Notion integration has been granted access to the target pages:\n\n1. Visit the target page in Notion\n2. Click on the three dots menu\n3. Select \"Connect to integration\"\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n---\n\n\n\n## npm Installation and Configuration\n\n### 相关页面\n\n相关主题：[Docker Deployment](#page-docker-deployment), [Quick Start Guide](#page-quickstart)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n
\n\n# npm Installation and Configuration\n\nThe Notion MCP Server is a Model Context Protocol (MCP) server that exposes the Notion API as MCP tools. This page covers all aspects of installing and configuring the server using npm, including setup for various AI client applications, environment configuration, and local development workflows.\n\n## Overview\n\nThe server is distributed as an npm package (`@notionhq/notion-mcp-server`) and can be installed via `npx` for immediate use or added to projects for development. It supports two transport modes: `stdio` for local MCP clients and `http` for remote access with authentication.\n\n| Transport Mode | Use Case | Authentication |\n|----------------|----------|----------------|\n| `stdio` | Local MCP clients (Cursor, Claude Desktop) | Via `NOTION_TOKEN` env var |\n| `http` | Remote access, development servers | Bearer token (auto-generated or custom) |\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Prerequisites\n\nBefore installing the Notion MCP Server, ensure you have:\n\n- **Node.js** version compatible with the package requirements\n- **npm** or **npx** for package management\n- A **Notion integration token** from the [Notion Developer Portal](https://www.notion.so/my-integrations)\n\n### Obtaining Your Notion Integration Token\n\n1. Navigate to [Notion Developer Portal](https://www.notion.so/my-integrations)\n2. Create a new integration or select an existing one\n3. Copy the **Internal Integration Token** (format: `ntn_...`)\n4. Share the target Notion pages with your integration by opening the page and selecting **\"Connect to integration\"**\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Installation Methods\n\n### Using npx (Recommended for Immediate Use)\n\nThe simplest method to run the server without global installation:\n\n```bash\nnpx -y @notionhq/notion-mcp-server\n```\n\nFor stdio transport (default):\n\n```bash\nnpx -y @notionhq/notion-mcp-server --transport stdio\n```\n\nFor HTTP transport with auto-generated auth token:\n\n```bash\nnpx -y @notionhq/notion-mcp-server --transport http\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Local Development Installation\n\nFor testing changes or contributing to the project:\n\n```bash\n# Clone the repository\ngit clone https://github.com/makenotion/notion-mcp-server.git\ncd notion-mcp-server\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\nThe build script compiles TypeScript and bundles the CLI:\n\n```bash\nnpm run build # TypeScript compilation + CLI bundling\nnpm test # Run vitest tests\nnpm run dev # Start dev server with hot reload\n```\n\n资料来源：[CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md) and [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n### Using npm link for Local Testing\n\nTo test local changes in AI clients without publishing:\n\n```bash\n# From repository root\nnpm link\n\n# The command creates a machine-global symlink\n# to the notion-mcp-server package\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Environment Configuration\n\n### Environment Variables\n\n| Variable | Description | Required | Priority |\n|----------|-------------|----------|----------|\n| `NOTION_TOKEN` | Notion integration token (`ntn_...`) | Yes (for stdio) | Recommended |\n| `OPENAPI_MCP_HEADERS` | JSON string with custom headers | Alternative to `NOTION_TOKEN` | Alternative |\n| `AUTH_TOKEN` | Bearer token for HTTP transport auth | No (for HTTP) | Lower than CLI arg |\n| `NODE_ENV` | Set to `test` for running tests | For testing | N/A |\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts) and [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Using NOTION_TOKEN (Recommended)\n\n```bash\nNOTION_TOKEN=\"ntn_your_integration_token\" npx -y @notionhq/notion-mcp-server\n```\n\n### Using OPENAPI_MCP_HEADERS (Advanced)\n\nFor custom headers including Notion-Version specification:\n\n```bash\nOPENAPI_MCP_HEADERS='{\"Authorization\": \"Bearer ntn_your_token\", \"Notion-Version\": \"2025-09-03\"}' \\\n npx -y @notionhq/notion-mcp-server\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## MCP Client Configuration\n\n### Cursor & Claude Desktop\n\nAdd configuration to your client's MCP settings file:\n\n**Cursor:** `~/.cursor/mcp.json` \n**Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n#### Option 1: Using NOTION_TOKEN (Recommended)\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_your_integration_token\"\n }\n }\n }\n}\n```\n\n#### Option 2: Using OPENAPI_MCP_HEADERS\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_your_token\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\"}\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Zed Editor\n\nAdd to `settings.json`:\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_your_token\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\"}\"\n }\n },\n \"settings\": {}\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### GitHub Copilot CLI\n\nUse interactive addition:\n\n```bash\n/mcp add\n```\n\nOr manually edit `~/.copilot/mcp-config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_your_integration_token\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Testing Local Changes in Cursor\n\nFor testing local development changes:\n\n1. Run `npm link` from the repository root\n2. Merge this configuration into `~/.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_your_integration_token\"\n }\n }\n }\n}\n```\n\n3. After testing, run `npm unlink` to cleanup\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## HTTP Transport Configuration\n\n### Command Line Options\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http [options]\n```\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--transport ` | Transport type: `stdio` or `http` | `stdio` |\n| `--port ` | Port for HTTP server | `3000` |\n| `--auth-token ` | Bearer token for authentication | Auto-generated |\n| `--disable-auth` | Disable bearer token authentication | `false` |\n| `--help`, `-h` | Show help message | N/A |\n\nThe `--auth-token` argument takes precedence over the `AUTH_TOKEN` environment variable.\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts) and [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Authentication Options for HTTP Transport\n\n#### Option 1: Auto-generated Token (Development Only)\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http\n```\n\nThe server displays the generated token:\n\n```\nGenerated auth token: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\nUse this token in the Authorization header: Bearer a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\n```\n\n#### Option 2: Custom Token via CLI (Recommended for Production)\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\n#### Option 3: Custom Token via Environment Variable\n\n```bash\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq/notion-mcp-server --transport http\n```\n\n### Making HTTP Requests\n\nAll requests require the bearer token in the Authorization header:\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Docker Installation\n\n### Option 1: Using Official Docker Hub Image\n\n#### With NOTION_TOKEN\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\", \"NOTION_TOKEN\",\n \"mcp/notion\"\n ],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_your_integration_token\"\n }\n }\n }\n}\n```\n\n#### With OPENAPI_MCP_HEADERS\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\", \"OPENAPI_MCP_HEADERS\",\n \"mcp/notion\"\n ],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\":\\\"Bearer ntn_your_token\\\",\\\"Notion-Version\\\":\\\"2025-09-03\\\"}\"\n }\n }\n }\n}\n```\n\n### Option 2: Building Locally\n\n```bash\n# Build the Docker image\ndocker compose build\n\n# Run with local image\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN=ntn_your_token\",\n \"notion-mcp-server\"\n ]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Available Scripts\n\n| Script | Description |\n|--------|-------------|\n| `npm run build` | Compiles TypeScript and bundles the CLI |\n| `npm run dev` | Starts dev server with hot reload using tsx |\n| `npm test` | Runs vitest tests |\n| `npm run test:watch` | Runs tests in watch mode |\n| `npm run test:coverage` | Runs tests with coverage report |\n\n资料来源：[package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json) and [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n## Package Metadata\n\n| Property | Value |\n|----------|-------|\n| Package Name | `@notionhq/notion-mcp-server` |\n| Version | 2.3.0 |\n| License | MIT |\n| CLI Entry | `bin/cli.mjs` |\n| Main Entry | `index.js` |\n| Type | ES Module |\n\n资料来源：[package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Token not recognized | Ensure `NOTION_TOKEN` or `OPENAPI_MCP_HEADERS` is set in environment |\n| JSON parsing errors | Check that `OPENAPI_MCP_HEADERS` is properly escaped JSON |\n| Client can't connect | Verify integration has access to the target Notion pages |\n| Local changes not reflected | Run `npm unlink` then `npm link` again |\n\n### Verifying Installation\n\nTest the server can start:\n\n```bash\nnpx -y @notionhq/notion-mcp-server --help\n```\n\nExpected output shows available options including `--transport`, `--port`, `--auth-token`, and `--help`.\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n---\n\n\n\n## Docker Deployment\n\n### 相关页面\n\n相关主题：[npm Installation and Configuration](#page-npm-installation), [Transport Layers](#page-transport-layers)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [Dockerfile](https://github.com/makenotion/notion-mcp-server/blob/main/Dockerfile)\n- [docker-compose.yml](https://github.com/makenotion/notion-mcp-server/blob/main/docker-compose.yml)\n- [.dockerignore](https://github.com/makenotion/notion-mcp-server/blob/main/.dockerignore)\n
\n\n# Docker Deployment\n\nThe notion-mcp-server provides official Docker container support for running the MCP server in a containerized environment. This deployment option is ideal for users who prefer not to install Node.js dependencies locally or want to ensure consistent runtime environments across different systems.\n\n## Overview\n\nThe Docker deployment for notion-mcp-server offers two primary approaches for containerization:\n\n| Approach | Description | Use Case |\n|---------|-------------|----------|\n| **Official Image** | Use pre-built image from Docker Hub (`mcp/notion`) | Quick setup, no build required |\n| **Local Build** | Build image locally using `docker compose` | Development, customization |\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Client App
Cursor/Claude/Zed] --> B[MCP Client Config]\n B --> C[Docker Container
notion-mcp-server]\n C --> D[Notion API
api.notion.com]\n \n E[Environment Variables] --> C\n E --> F[NOTION_TOKEN]\n E --> G[OPENAPI_MCP_HEADERS]\n E --> H[AUTH_TOKEN
HTTP transport only]\n```\n\n## Environment Configuration\n\n### Required Variables\n\n| Variable | Description | Required | Example |\n|----------|-------------|----------|---------|\n| `NOTION_TOKEN` | Notion integration secret | Yes (recommended) | `ntn_****` |\n| `OPENAPI_MCP_HEADERS` | JSON string with custom headers | No (alternative) | `{\"Authorization\": \"Bearer ntn_****\"}` |\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Authentication Token (HTTP Transport)\n\nWhen using the HTTP transport mode, an additional bearer token is required:\n\n| Variable | CLI Argument | Priority |\n|----------|-------------|----------|\n| `AUTH_TOKEN` | `--auth-token` | Lower |\n| Environment variable | `--auth-token` argument | Higher (overrides env var) |\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Deployment Options\n\n### Option 1: Using Official Docker Hub Image\n\nThe official image is available at `mcp/notion` on Docker Hub.\n\n#### STDIO Transport Configuration\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN\",\n \"mcp/notion\"\n ],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n#### HTTP Transport Configuration\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN\",\n \"mcp/notion\",\n \"--transport\",\n \"http\",\n \"--port\",\n \"3000\",\n \"--auth-token\",\n \"your-secret-token\"\n ],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### Option 2: Building Locally with Docker Compose\n\n#### Build Process\n\n```bash\n# Build the Docker image\ndocker compose build\n```\n\n#### Configuration for Local Build\n\nReplace `mcp/notion` with `notion-mcp-server` in your MCP client configuration:\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN=ntn_****\",\n \"notion-mcp-server\"\n ]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## HTTP Transport with Docker\n\nWhen running with Docker, the HTTP transport requires special handling for headers and authentication.\n\n### Authentication Modes\n\n```mermaid\ngraph LR\n A[Docker Container] --> B{Transport Mode}\n B -->|stdio| C[No Auth Required]\n B -->|http| D[Bearer Token Required]\n \n E[Request] --> F[Authorization Header]\n F --> D\n D --> G{Token Valid?}\n G -->|Yes| H[Process Request]\n G -->|No| I[401 Unauthorized]\n```\n\n### Request Format\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Integration Setup\n\n### Notion Workspace Configuration\n\nBefore using the Docker container, ensure your integration has access to target pages:\n\n1. Visit the target Notion page\n2. Click on the **three dots menu** (⋮)\n3. Select **\"Connect to integration\"**\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Client-Specific Configuration\n\n| Client | Configuration File | Example |\n|--------|-------------------|---------|\n| Cursor | `.cursor/mcp.json` | [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md) |\n| Claude Desktop | `claude_desktop_config.json` | `~/Library/Application Support/Claude/` |\n| Zed | `settings.json` | `context_servers` section |\n| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | Interactive `/mcp add` or manual edit |\n\n## Environment Variable Priority\n\n```mermaid\ngraph TD\n A[Runtime] --> B{Environment Check}\n B --> C[NOTION_TOKEN Set?]\n B --> D[OPENAPI_MCP_HEADERS Set?]\n \n C -->|Yes| E[Use NOTION_TOKEN]\n C -->|No| F[Use OPENAPI_MCP_HEADERS]\n \n D -->|Yes| G[Use Custom Headers]\n D -->|No| H[Error: Missing Token]\n```\n\n| Priority | Variable | Notes |\n|----------|----------|-------|\n| 1 | `NOTION_TOKEN` | Recommended for most use cases |\n| 2 | `OPENAPI_MCP_HEADERS` | For advanced header customization |\n\n## Build Commands Reference\n\n| Command | Description |\n|---------|-------------|\n| `npm run build` | TypeScript compilation + CLI bundling |\n| `docker compose build` | Build Docker image locally |\n| `npm test` | Run vitest tests |\n\n资料来源：[package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json), [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Security Considerations\n\n### Token Handling\n\n- **Never commit tokens** to version control\n- Use environment variables or secret management tools\n- Rotate tokens periodically through Notion developer portal\n\n### Network Security\n\n- The HTTP transport binds to `http://0.0.0.0:/mcp`\n- Always use authentication tokens for HTTP transport in production\n- Consider network isolation based on your deployment environment\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| Container exits immediately | Verify `NOTION_TOKEN` is valid and set correctly |\n| Authentication failures | Check bearer token matches `--auth-token` argument |\n| Port conflicts | Change port using `--port` argument |\n| Permission denied | Ensure Docker daemon is running and user has Docker permissions |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：makenotion/notion-mcp-server\n\n摘要：发现 21 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：配置坑 - 来源证据：BUG: Tool `query_data_sources` not available。\n\n## 1. 配置坑 · 来源证据：BUG: Tool `query_data_sources` not available\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：BUG: Tool `query_data_sources` not available\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eef5bea2e30f4ef6b0ebbec184ad57bc | https://github.com/makenotion/notion-mcp-server/issues/256 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e292459f0a6b4c38ab30d85d1fed7988 | https://github.com/makenotion/notion-mcp-server/issues/232 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missing POST /v1/databases tool\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_00471efb0dd04e9a998d767773687158 | https://github.com/makenotion/notion-mcp-server/issues/218 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c42a4b966290466e9d4c8678f1530d70 | https://github.com/makenotion/notion-mcp-server/issues/269 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：Notion MCP server does not work with Claude Code\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Notion MCP server does not work with Claude Code\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f225074bf40440978c5542d0a0553a33 | https://github.com/makenotion/notion-mcp-server/issues/277 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 6. 安全/权限坑 · 来源证据：OAuth token expires too frequently — requires re-authentication 3+ times per week\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token expires too frequently — requires re-authentication 3+ times per week\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6e81d503097248cb8099528ad547bc67 | https://github.com/makenotion/notion-mcp-server/issues/225 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Feature Request: Property-based filtering in notion-search for database queries\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Property-based filtering in notion-search for database queries\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b9e32ab88c7e48818bc99b84652be1ab | https://github.com/makenotion/notion-mcp-server/issues/278 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：Ontheia listed as compatible client — works great with notion-mcp-server\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ontheia listed as compatible client — works great with notion-mcp-server\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3fc1b045a8d44d0fb100ada453a88281 | https://github.com/makenotion/notion-mcp-server/issues/287 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cf7210b63f984b539554678f387c7e82 | https://github.com/makenotion/notion-mcp-server/issues/283 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 配置坑 · 来源证据：Enhancement: Expand blockObjectRequest to support all Notion block types\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Expand blockObjectRequest to support all Notion block types\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1dca271be3594278a2b6cae74a5a3caf | https://github.com/makenotion/notion-mcp-server/issues/282 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 配置坑 · 来源证据：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6ed1925ce08546dabe29e4f24e8a5967 | https://github.com/makenotion/notion-mcp-server/issues/281 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：Schema quality: 8 required parameters missing descriptions\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Schema quality: 8 required parameters missing descriptions\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3874c96ff07545e58a89907777de0799 | https://github.com/makenotion/notion-mcp-server/issues/280 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 维护坑 · 来源证据：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_201ffa8849a546d7aa12e1ea13455afb | https://github.com/makenotion/notion-mcp-server/issues/286 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | last_activity_observed missing\n\n## 16. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 来源证据：v2.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6bd57dcedd924ba5a565340c6538b43c | https://github.com/makenotion/notion-mcp-server/releases/tag/v2.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR me…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR merge)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_805c993b34ef42b88c0832132f5794fc | https://github.com/makenotion/notion-mcp-server/issues/284 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | release_recency=unknown\n\n\n", "markdown_key": "notion-mcp-server", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:946169991", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/makenotion/notion-mcp-server" }, { "evidence_id": "art_bfa1c23dbdf04dfb9dd7a72bb6d25333", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/makenotion/notion-mcp-server#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "notion-mcp-server 说明书", "toc": [ "https://github.com/makenotion/notion-mcp-server 项目说明书", "目录", "Introduction to Notion MCP Server", "Overview", "Architecture", "File Structure", "Installation and Configuration", "Transport Modes", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "3bef7addac59b237da3bb41f36a520babc47fa3c", "repo_inspection_error": null, "repo_inspection_files": [ "Dockerfile", "package.json", "README.md", "docker-compose.yml", "src/init-server.ts", "src/openapi-mcp-server/index.ts", "src/openapi-mcp-server/README.md", "src/openapi-mcp-server/mcp/proxy.ts", "src/openapi-mcp-server/client/polyfill-headers.ts", "src/openapi-mcp-server/client/http-client.ts", "src/openapi-mcp-server/openapi/parser.ts", "src/openapi-mcp-server/openapi/file-upload.ts", "src/openapi-mcp-server/auth/template.ts", "src/openapi-mcp-server/auth/index.ts", "src/openapi-mcp-server/auth/types.ts", "src/openapi-mcp-server/mcp/__tests__/proxy.test.ts", "src/openapi-mcp-server/client/__tests__/http-client.integration.test.ts", "src/openapi-mcp-server/client/__tests__/http-client.test.ts", "src/openapi-mcp-server/client/__tests__/http-client-upload.test.ts", "src/openapi-mcp-server/openapi/__tests__/parser-multipart.test.ts", "src/openapi-mcp-server/openapi/__tests__/parser.test.ts", "src/openapi-mcp-server/openapi/__tests__/file-upload.test.ts" ], "repo_inspection_verified": true, "review_reasons": [], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# @notionhq/notion-mcp-server - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @notionhq/notion-mcp-server 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npx @notionhq/notion-mcp-server` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86 等\n- `npx @notionhq/notion-mcp-server --transport stdio` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `npx @notionhq/notion-mcp-server --transport http` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86\n- `npx @notionhq/notion-mcp-server --transport http --port 8080` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `curl -H \"Authorization: Bearer your-token-here\" \\` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server` 证据：`README.md` Claim：`clm_0009` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `scripts/start-server.ts`, `src/openapi-mcp-server/mcp/__tests__/proxy.test.ts`, `src/openapi-mcp-server/mcp/proxy.ts`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0010` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0011` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：33\n- 重要文件覆盖：16/33\n- 证据索引条目：16\n- 角色 / Skill 条目：4\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @notionhq/notion-mcp-server 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @notionhq/notion-mcp-server 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @notionhq/notion-mcp-server 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 4 个角色 / Skill / 项目文档条目。\n\n- **CLAUDE.md**（project_doc）：This file provides guidance for Claude Code when working with this repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **Notion MCP Server**（project_doc）：!NOTE We’ve introduced Notion MCP , a remote MCP server with the following improvements: - Easy installation via standard OAuth. No need to fiddle with JSON or API tokens anymore. - Powerful tools tailored to AI agents, including editing pages in Markdown. These tools are designed with optimized token consumption in mind. Learn more and get started at Notion MCP documentation https://developers.notion.com/docs/mcp .… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Readme**（project_doc）：Note: This is a fork from v1 of https://github.com/snaggle-ai/openapi-mcp-server. The library took a different direction with v2 which is not compatible with our development approach. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`src/openapi-mcp-server/README.md`\n- **Description**（project_doc）：- Automated test unit, integration, etc. - Manual test provide reproducible testing steps below 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/pull_request_template.md`\n\n## 证据索引\n\n- 共索引 16 条证据。\n\n- **CLAUDE.md**（documentation）：This file provides guidance for Claude Code when working with this repository. 证据：`CLAUDE.md`\n- **Notion MCP Server**（documentation）：!NOTE We’ve introduced Notion MCP , a remote MCP server with the following improvements: - Easy installation via standard OAuth. No need to fiddle with JSON or API tokens anymore. - Powerful tools tailored to AI agents, including editing pages in Markdown. These tools are designed with optimized token consumption in mind. Learn more and get started at Notion MCP documentation https://developers.notion.com/docs/mcp . We are prioritizing, and only providing active support for, Notion MCP remote . As a result: - We may sunset this local MCP server repository in the future. - Issues and pull requests here are not actively monitored. - Please do not file issues relating to the remote MCP here; i… 证据：`README.md`\n- **Readme**（documentation）：Note: This is a fork from v1 of https://github.com/snaggle-ai/openapi-mcp-server. The library took a different direction with v2 which is not compatible with our development approach. 证据：`src/openapi-mcp-server/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@notionhq/notion-mcp-server\", \"keywords\": \"notion\", \"api\", \"mcp\", \"server\" , \"version\": \"2.3.0\", \"license\": \"MIT\", \"type\": \"module\", \"scripts\": { \"build\": \"tsc -build && node scripts/build-cli.js\", \"dev\": \"tsx watch scripts/start-server.ts\", \"test\": \"NODE ENV=test vitest run\", \"test:watch\": \"NODE ENV=test vitest\", \"test:coverage\": \"NODE ENV=test vitest run --coverage\" }, \"bin\": { \"notion-mcp-server\": \"bin/cli.mjs\" }, \"dependencies\": { \"@modelcontextprotocol/sdk\": \"^1.25.1\", \"axios\": \"^1.8.4\", \"express\": \"^4.21.2\", \"form-data\": \"^4.0.1\", \"mustache\": \"^4.2.0\", \"node-fetch\": \"^3.3.2\", \"openapi-client-axios\": \"^7.5.5\", \"openapi-schema-validator\": \"^12.1.3\", \"openapi-types\": \"^12.1.3\"… 证据：`package.json`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Description**（documentation）：- Automated test unit, integration, etc. - Manual test provide reproducible testing steps below 证据：`.github/pull_request_template.md`\n- **Notion Openapi**（structured_config）：{ \"openapi\": \"3.1.0\", \"info\": { \"title\": \"Notion API\", \"version\": \"2.0.0\", \"description\": \"Notion API 2025-09-03 - Data Source Edition. Breaking change: Database endpoints replaced with data source endpoints.\", \"license\": { \"name\": \"MIT\", \"url\": \"https://github.com/makenotion/notion-sdk-js/blob/main/LICENSE\" } }, \"servers\": { \"url\": \"https://api.notion.com\" } , \"components\": { \"securitySchemes\": { \"bearerAuth\": { \"type\": \"http\", \"scheme\": \"bearer\" }, \"basicAuth\": { \"type\": \"http\", \"scheme\": \"basic\" } }, \"parameters\": { \"notionVersion\": { \"name\": \"Notion-Version\", \"in\": \"header\", \"required\": false, \"schema\": { \"type\": \"string\", \"default\": \"2025-09-03\" }, \"description\": \"The Notion API versio… 证据：`scripts/notion-openapi.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"composite\": true, \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true, \"outDir\": \"./build\", \"target\": \"es2021\", \"lib\": \"es2022\" , \"jsx\": \"react-jsx\", \"module\": \"es2022\", \"moduleResolution\": \"Bundler\", \"types\": \"node\" , \"resolveJsonModule\": true, \"allowJs\": true, \"checkJs\": false, \"isolatedModules\": true, \"allowSyntheticDefaultImports\": true, \"forceConsistentCasingInFileNames\": true, \"strict\": true, \"skipLibCheck\": true }, \"include\": \"test/ / .ts\", \"scripts/ / .ts\", \"src/ / .ts\" } 证据：`tsconfig.json`\n- **.dockerignore**（source_file）：node modules Dockerfile docker-compose.yml 证据：`.dockerignore`\n- **.gitignore**（source_file）：node modules/ build/ dist bin/ .cache .yarn/cache .eslintcache .cursor .DS Store 证据：`.gitignore`\n- **syntax=docker/dockerfile:1**（source_file）：Use Node.js LTS as the base image FROM node:20-slim AS builder 证据：`Dockerfile`\n- **Docker Compose**（source_file）：services: notion-mcp-server: build: . stdin open: true tty: true restart: unless-stopped 证据：`docker-compose.yml`\n- **Build Cli**（source_file）：import as esbuild from 'esbuild'; import { chmod } from 'fs/promises'; import { fileURLToPath } from 'url'; import { dirname, join } from 'path'; 证据：`scripts/build-cli.js`\n- **Start Server**（source_file）：import path from 'node:path' import { fileURLToPath } from 'url' import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js' import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js' import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js' import { randomUUID, randomBytes } from 'node:crypto' import fs from 'node:fs' import os from 'node:os' import express from 'express' 证据：`scripts/start-server.ts`\n- **Init Server**（source_file）：import fs from 'node:fs' import path from 'node:path' 证据：`src/init-server.ts`\n- **Vitest.Config**（source_file）：import { defineConfig } from 'vitest/config' 证据：`vitest.config.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`CLAUDE.md`, `README.md`, `src/openapi-mcp-server/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`CLAUDE.md`, `README.md`, `src/openapi-mcp-server/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Introduction to Notion MCP Server**：importance `high`\n - source_paths: README.md, package.json, CLAUDE.md\n- **Quick Start Guide**：importance `high`\n - source_paths: README.md, src/init-server.ts\n- **System Architecture**：importance `high`\n - source_paths: src/openapi-mcp-server/index.ts, src/openapi-mcp-server/client/http-client.ts, src/openapi-mcp-server/openapi/parser.ts, src/openapi-mcp-server/auth/index.ts, src/openapi-mcp-server/auth/types.ts\n- **Transport Layers**：importance `high`\n - source_paths: src/init-server.ts, scripts/start-server.ts\n- **MCP Proxy Implementation**：importance `medium`\n - source_paths: src/openapi-mcp-server/mcp/proxy.ts, src/openapi-mcp-server/index.ts\n- **Available MCP Tools**：importance `high`\n - source_paths: scripts/notion-openapi.json, README.md\n- **Data Sources (v2.0.0 Breaking Changes)**：importance `high`\n - source_paths: README.md, scripts/notion-openapi.json\n- **Authentication System**：importance `high`\n - source_paths: src/openapi-mcp-server/auth/index.ts, src/openapi-mcp-server/auth/types.ts, src/openapi-mcp-server/auth/template.ts, src/openapi-mcp-server/client/polyfill-headers.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `3bef7addac59b237da3bb41f36a520babc47fa3c`\n- inspected_files: `Dockerfile`, `package.json`, `README.md`, `docker-compose.yml`, `src/init-server.ts`, `src/openapi-mcp-server/index.ts`, `src/openapi-mcp-server/README.md`, `src/openapi-mcp-server/mcp/proxy.ts`, `src/openapi-mcp-server/client/polyfill-headers.ts`, `src/openapi-mcp-server/client/http-client.ts`, `src/openapi-mcp-server/openapi/parser.ts`, `src/openapi-mcp-server/openapi/file-upload.ts`, `src/openapi-mcp-server/auth/template.ts`, `src/openapi-mcp-server/auth/index.ts`, `src/openapi-mcp-server/auth/types.ts`, `src/openapi-mcp-server/mcp/__tests__/proxy.test.ts`, `src/openapi-mcp-server/client/__tests__/http-client.integration.test.ts`, `src/openapi-mcp-server/client/__tests__/http-client.test.ts`, `src/openapi-mcp-server/client/__tests__/http-client-upload.test.ts`, `src/openapi-mcp-server/openapi/__tests__/parser-multipart.test.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：BUG: Tool `query_data_sources` not available\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：BUG: Tool `query_data_sources` not available\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_eef5bea2e30f4ef6b0ebbec184ad57bc | https://github.com/makenotion/notion-mcp-server/issues/256 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_e292459f0a6b4c38ab30d85d1fed7988 | https://github.com/makenotion/notion-mcp-server/issues/232 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missing POST /v1/databases tool\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_00471efb0dd04e9a998d767773687158 | https://github.com/makenotion/notion-mcp-server/issues/218 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_c42a4b966290466e9d4c8678f1530d70 | https://github.com/makenotion/notion-mcp-server/issues/269 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Notion MCP server does not work with Claude Code\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Notion MCP server does not work with Claude Code\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_f225074bf40440978c5542d0a0553a33 | https://github.com/makenotion/notion-mcp-server/issues/277 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：OAuth token expires too frequently — requires re-authentication 3+ times per week\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token expires too frequently — requires re-authentication 3+ times per week\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_6e81d503097248cb8099528ad547bc67 | https://github.com/makenotion/notion-mcp-server/issues/225 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：Feature Request: Property-based filtering in notion-search for database queries\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Property-based filtering in notion-search for database queries\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_b9e32ab88c7e48818bc99b84652be1ab | https://github.com/makenotion/notion-mcp-server/issues/278 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Ontheia listed as compatible client — works great with notion-mcp-server\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ontheia listed as compatible client — works great with notion-mcp-server\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3fc1b045a8d44d0fb100ada453a88281 | https://github.com/makenotion/notion-mcp-server/issues/287 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_cf7210b63f984b539554678f387c7e82 | https://github.com/makenotion/notion-mcp-server/issues/283 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：Enhancement: Expand blockObjectRequest to support all Notion block types\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Expand blockObjectRequest to support all Notion block types\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_1dca271be3594278a2b6cae74a5a3caf | https://github.com/makenotion/notion-mcp-server/issues/282 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：makenotion/notion-mcp-server\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：BUG: Tool `query_data_sources` not available（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Notion MCP server does not work with Claude Code（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/makenotion/notion-mcp-server 项目说明书\n\n生成时间：2026-05-16 23:53:23 UTC\n\n## 目录\n\n- [Introduction to Notion MCP Server](#page-introduction)\n- [Quick Start Guide](#page-quickstart)\n- [System Architecture](#page-architecture)\n- [Transport Layers](#page-transport-layers)\n- [MCP Proxy Implementation](#page-mcp-proxy)\n- [Available MCP Tools](#page-available-tools)\n- [Data Sources (v2.0.0 Breaking Changes)](#page-data-sources-v2)\n- [Authentication System](#page-authentication)\n- [npm Installation and Configuration](#page-npm-installation)\n- [Docker Deployment](#page-docker-deployment)\n\n\n\n## Introduction to Notion MCP Server\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#page-quickstart), [System Architecture](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n
\n\n# Introduction to Notion MCP Server\n\nThe Notion MCP Server is an official implementation of the [Model Context Protocol (MCP)](https://spec.modelcontextprotocol.io/) server that exposes the [Notion API](https://developers.notion.com/reference/intro) as MCP tools. It enables AI assistants and agents to interact with Notion workspaces through a standardized protocol, allowing them to search, read, create, and modify Notion pages, databases, and content.\n\n## Overview\n\nThe MCP server acts as a bridge between AI clients (such as Claude, Cursor, or GitHub Copilot) and the Notion API. Instead of manually implementing API calls, AI agents can discover and invoke MCP tools dynamically, making it easier to build AI-powered Notion integrations.\n\n### Key Characteristics\n\n| Attribute | Value |\n|-----------|-------|\n| **Package Name** | `@notionhq/notion-mcp-server` |\n| **Current Version** | 2.3.0 |\n| **License** | MIT |\n| **API Version** | 2025-09-03 (Data Source Edition) |\n| **Node.js Support** | 18+ (with Headers polyfill for older versions) |\n| **Transport Modes** | stdio, Streamable HTTP |\n| **Total Tools** | 22 |\n\n资料来源：[README.md:1-30]()[package.json:7-10]()\n\n## Architecture\n\nThe Notion MCP Server follows a layered architecture that auto-generates tools from an OpenAPI specification. This design ensures that any updates to the Notion API are automatically reflected in the available MCP tools without requiring code changes.\n\n### High-Level Flow\n\n```mermaid\ngraph TD\n A[scripts/notion-openapi.json] --> B[OpenAPIToMCPConverter]\n B --> C[MCPProxy]\n C --> D[MCP SDK]\n D --> E[AI Client]\n \n F[User Request] --> E\n E --> G[Tool Call]\n G --> H[HTTP Client]\n H --> I[Notion API]\n I --> H --> G --> F\n```\n\n资料来源：[CLAUDE.md:1-30]()\n\n### Component Architecture\n\n```mermaid\ngraph TD\n subgraph \"Entry Point\"\n A[scripts/start-server.ts]\n end\n \n subgraph \"Server Initialization\"\n B[src/init-server.ts]\n end\n \n subgraph \"Core Implementation\"\n C[openapi/parser.ts]\n D[mcp/proxy.ts]\n E[client/http-client.ts]\n end\n \n A --> B --> C\n C --> D\n D --> E\n E --> F[Notion API]\n```\n\nThe server initialization process follows these steps:\n\n1. **Load OpenAPI Spec**: The server loads `scripts/notion-openapi.json` which defines all Notion API endpoints in OpenAPI 3.1.0 format\n2. **Validate Spec**: The spec is validated against OpenAPI schema requirements\n3. **Create MCPProxy**: A new MCPProxy instance is created with the validated spec\n4. **Register Tools**: `MCPProxy.setupHandlers()` registers all discovered tools with the MCP SDK\n5. **Start Transport**: The server starts listening on the configured transport (stdio or HTTP)\n\n资料来源：[CLAUDE.md:15-45]()[scripts/start-server.ts:1-50]()\n\n### Tool Generation Flow\n\nTools are automatically generated from the OpenAPI specification through a conversion process:\n\n```mermaid\ngraph LR\n A[OpenAPI Operation] --> B[Extract operationId]\n B --> C[Parse Parameters]\n C --> D[Parse Request Body]\n D --> E[Parse Response Schema]\n E --> F[Create MCP Tool]\n \n G[Path + Method] --> A\n H[inputSchema] --> F\n I[returnSchema] --> F\n```\n\n1. `OpenAPIToMCPConverter.convertToMCPTools()` iterates through all paths and operations in the OpenAPI spec\n2. Each operation becomes an MCP tool where the name is derived from `operationId`\n3. Operation parameters and request body are combined into the tool's `inputSchema`\n4. The response schema becomes the tool's `returnSchema`\n5. `MCPProxy.setupHandlers()` registers the tools with the MCP SDK\n\n资料来源：[CLAUDE.md:30-50]()[src/openapi-mcp-server/openapi/parser.ts:1-50]()\n\n## File Structure\n\nThe repository is organized as follows:\n\n```\nnotion-mcp-server/\n├── scripts/\n│ ├── notion-openapi.json # OpenAPI 3.1.0 specification\n│ └── start-server.ts # CLI entry point\n├── src/\n│ ├── init-server.ts # Server initialization\n│ └── openapi-mcp-server/\n│ ├── openapi/\n│ │ └── parser.ts # OpenAPI to MCP conversion\n│ ├── mcp/\n│ │ └── proxy.ts # Tool registration & execution\n│ └── client/\n│ ├── http-client.ts # HTTP request execution\n│ └── polyfill-headers.ts # Node.js Headers polyfill\n├── bin/\n│ └── cli.mjs # Bundled CLI\n└── package.json # Package configuration\n```\n\n| File | Purpose | Lines |\n|------|---------|-------|\n| `scripts/notion-openapi.json` | Source of truth for all tools | - |\n| `src/init-server.ts` | Loads & validates spec, creates MCPProxy | - |\n| `src/openapi-mcp-server/openapi/parser.ts` | Converts OpenAPI → MCP tools | ~529 |\n| `src/openapi-mcp-server/mcp/proxy.ts` | MCP tool registration and execution | ~209 |\n| `src/openapi-mcp-server/client/http-client.ts` | Executes API calls via axios | ~198 |\n\n资料来源：[CLAUDE.md:50-65]()\n\n## Installation and Configuration\n\n### Prerequisites\n\n- Node.js 18 or higher\n- A Notion integration token (from [Notion integrations page](https://www.notion.so/profile/integrations))\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `NOTION_TOKEN` | Notion integration secret (recommended) | Yes |\n| `OPENAPI_MCP_HEADERS` | JSON string with custom headers | Alternative |\n| `AUTH_TOKEN` | Bearer token for HTTP transport authentication | For HTTP mode |\n| `NOTION_API_URL` | Override Notion API base URL | No |\n\n资料来源：[README.md:80-120]()\n\n### npm Installation\n\nFor Cursor, Claude Desktop, and similar clients:\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\nFor Zed editor:\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"]\n },\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\"}\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:100-140]()\n\n### Docker Installation\n\nUsing the official Docker Hub image:\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"NOTION_TOKEN\", \"mcp/notion\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\nOr building locally with docker-compose:\n\n```bash\ndocker compose build\n```\n\n资料来源：[README.md:180-220]()\n\n## Transport Modes\n\nThe server supports two transport modes for communication with MCP clients.\n\n### Standard I/O (stdio)\n\nThe default transport mode where the server communicates via stdin/stdout. This is suitable for local integrations and most IDE plugins.\n\n```bash\nnpx @notionhq/notion-mcp-server\n# or\nnotion-mcp-server\n```\n\n资料来源：[README.md:70-80]()\n\n### Streamable HTTP\n\nAn HTTP-based transport that enables remote connections and is suitable for network deployments.\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --port 3000\n```\n\nWhen using HTTP transport, the server is available at `http://0.0.0.0:/mcp`.\n\n#### HTTP Authentication\n\nThe HTTP transport requires bearer token authentication:\n\n| Method | Description |\n|--------|-------------|\n| Auto-generated token | `npx @notionhq/notion-mcp-server --transport http` |\n| CLI argument | `--auth-token \"your-secret-token\"` |\n| Environment variable | `AUTH_TOKEN=\"your-secret-token\"` |\n\nExample authenticated request:\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n资料来源：[scripts/start-server.ts:1-50]()[README.md:150-175]()\n\n## Available Tools\n\nThe server exposes 22 MCP tools generated from the Notion API OpenAPI specification. Tools are named using the `operationId` from the OpenAPI spec.\n\n### Tool Naming Convention\n\n- Tool names are derived from the OpenAPI `operationId` (e.g., `retrieve-a-database`)\n- Names are truncated to 64 characters and converted to title case for display\n- Parameters and response schemas are automatically extracted from the OpenAPI specification\n\n资料来源：[CLAUDE.md:45-50]()\n\n### Core Operations\n\n| Category | Example Tools |\n|----------|---------------|\n| **Pages** | `create-a-page`, `retrieve-a-page`, `update-a-page`, `archive-a-page`, `move-page` |\n| **Databases** | `retrieve-a-database`, `query-a-database` |\n| **Data Sources** | `create-a-data-source`, `retrieve-a-data-source`, `update-a-data-source`, `query-data-source`, `list-data-source-templates` |\n| **Search** | `search` |\n| **Comments** | `create-a-comment`, `retrieve-comments` |\n| **Users** | `list-users`, `retrieve-a-user` |\n| **Blocks** | Various block operations |\n\n### Version 2.0.0 Breaking Changes\n\nVersion 2.0.0 introduced significant changes to align with the Notion API 2025-09-03 (Data Source Edition):\n\n#### Removed Tools\n\n| Old Tool | Reason |\n|----------|--------|\n| `post-database-query` | Replaced by `query-data-source` |\n| `update-a-database` | Replaced by `update-a-data-source` |\n| `create-a-database` | Replaced by `create-a-data-source` |\n\n#### New Tools\n\n| New Tool | Description |\n|----------|-------------|\n| `query-data-source` | Query a data source with filters and sorts |\n| `retrieve-a-data-source` | Get metadata and schema for a data source |\n| `update-a-data-source` | Update data source properties |\n| `create-a-data-source` | Create a new data source |\n| `list-data-source-templates` | List available templates in a data source |\n| `move-page` | Move a page to a different parent location |\n| `retrieve-a-database` | Get database metadata including data source IDs |\n\n#### Parameter Changes\n\n| Change | Description |\n|--------|-------------|\n| `database_id` → `data_source_id` | All database operations now use data source ID |\n| Search filter values | Changed from `[\"page\", \"database\"]` to `[\"page\", \"data_source\"]` |\n| Page creation | Now supports both `page_id` and `database_id` parents |\n\n资料来源：[README.md:35-80]()\n\n## Parameter Handling\n\nThe MCP server includes sophisticated parameter deserialization to handle complex nested data structures passed through MCP clients.\n\n### JSON String Deserialization\n\nWhen AI clients pass JSON data as string parameters, the server automatically parses them:\n\n```mermaid\ngraph TD\n A[String Parameter] --> B{Starts with { or [?}\n B -->|Yes| C[Attempt JSON.parse]\n C --> D{Parse Success?}\n D -->|Yes| E{Result is Object/Array?}\n E -->|Yes| F[Return parsed value]\n E -->|No| G[Keep original string]\n D -->|No| G\n B -->|No| G\n```\n\nThis logic handles:\n- JSON objects passed as strings\n- JSON arrays passed as strings\n- Nested objects within arrays\n- Recursively nested objects\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:1-60]()\n\n## Development\n\n### Build and Test\n\n```bash\nnpm run build # TypeScript compilation + CLI bundling\nnpm test # Run vitest tests\nnpm run dev # Start dev server with hot reload\n```\n\n### Testing Changes Locally\n\n1. Run `npm link` from the repository root to create a machine-global symlink\n2. Add the following to your MCP client's configuration:\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n3. Cleanup by running `npm unlink` from the repository root\n\n### Adding New Endpoints\n\nThe architecture is designed so that **only `scripts/notion-openapi.json` needs to be modified** to add new tools. The tool generation is fully automated from the OpenAPI specification.\n\n资料来源：[README.md:250-280]()[CLAUDE.md:20-30]()\n\n### CLI Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--transport ` | Transport type: 'stdio' or 'http' | stdio |\n| `--port ` | Port for HTTP server | 3000 |\n| `--auth-token ` | Bearer token for HTTP auth | auto-generated |\n| `--disable-auth` | Disable HTTP bearer auth | - |\n| `--help`, `-h` | Show help message | - |\n\n```bash\n# Examples\nnotion-mcp-server # stdio (default)\nnotion-mcp-server --transport http # HTTP transport\nnotion-mcp-server --transport http --port 8080 # Custom port\nnotion-mcp-server --transport http --auth-token abc # With auth\n```\n\n资料来源：[scripts/start-server.ts:1-50]()\n\n## HTTP Client Implementation\n\nThe HTTP client uses axios for making requests to the Notion API and handles the conversion between MCP tool parameters and HTTP request components.\n\n### Request Processing Flow\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Client\n participant Server as MCP Server\n participant HTTP as HTTP Client\n participant Notion as Notion API\n \n MCP->>Server: Tool Call with params\n Server->>Server: Extract URL params\n Server->>Server: Extract body params\n Server->>HTTP: Build request config\n HTTP->>Notion: HTTP Request\n Notion-->>HTTP: Response\n HTTP-->>Server: Parsed response\n Server-->>MCP: Tool result\n```\n\n### Key Implementation Details\n\n- **Form Data Handling**: When form data is present, `formData.getHeaders()` is used for correct Content-Type\n- **Body Parameters**: JSON body is sent with `Content-Type: application/json`\n- **Header Conversion**: Axios response headers are converted to standard `Headers` objects\n- **Error Handling**: Missing operations throw descriptive errors\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-80]()\n\n## Dependencies\n\n| Dependency | Version | Purpose |\n|------------|---------|---------|\n| `@modelcontextprotocol/sdk` | ^1.25.1 | MCP protocol implementation |\n| `axios` | ^1.8.4 | HTTP client for Notion API |\n| `express` | ^4.21.2 | HTTP transport server |\n| `form-data` | ^4.0.1 | Multipart form handling |\n| `openapi-client-axios` | ^7.5.5 | OpenAPI client generation |\n| `yargs` | ^17.7.2 | CLI argument parsing |\n| `zod` | 3.24.1 | Schema validation |\n\n资料来源：[package.json:25-45]()\n\n## Future Considerations\n\n> [!NOTE]\n>\n> Notion has introduced **Notion MCP** (remote), a new remote MCP server with OAuth-based authentication and tools optimized for AI agents, including Markdown editing capabilities.\n>\n> The local MCP server repository may be sunset in the future. Issues and pull requests are not actively monitored. For the remote MCP server, please contact Notion support.\n\n资料来源：[README.md:1-25]()\n\n## Quick Reference\n\n### Common Commands\n\n```bash\n# Install and run\nnpx @notionhq/notion-mcp-server\n\n# Build from source\nnpm run build\nnpm test\n\n# Development\nnpm run dev\nnpm link # For local testing\n```\n\n### Integration Setup Checklist\n\n- [ ] Create Notion integration at [notion.so/profile/integrations](https://www.notion.so/profile/integrations)\n- [ ] Share target pages with the integration (Connections)\n- [ ] Configure MCP client with `NOTION_TOKEN` or `OPENAPI_MCP_HEADERS`\n- [ ] Test connectivity with a simple search or retrieval\n\n### File Paths Reference\n\n| Path | Description |\n|------|-------------|\n| `scripts/notion-openapi.json` | OpenAPI 3.1.0 spec for all tools |\n| `src/init-server.ts` | Server initialization |\n| `src/openapi-mcp-server/openapi/parser.ts` | OpenAPI → MCP conversion |\n| `src/openapi-mcp-server/mcp/proxy.ts` | Tool registration |\n| `src/openapi-mcp-server/client/http-client.ts` | API request execution |\n| `bin/cli.mjs` | Bundled CLI entry point |\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Introduction to Notion MCP Server](#page-introduction), [Authentication System](#page-authentication), [npm Installation and Configuration](#page-npm-installation)\n\n
\nRelated Source Files\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n
\n\n# Quick Start Guide\n\nThis guide provides everything you need to get started with the Notion MCP Server, from installation to running your first AI-assisted Notion operations.\n\n## Overview\n\nThe **Notion MCP Server** is a Model Context Protocol (MCP) server that exposes the Notion API as MCP tools, enabling AI assistants to interact with Notion workspaces. It auto-generates tools from an OpenAPI specification, providing 22 tools for operations like searching pages, creating content, querying databases, and managing comments.\n\n资料来源：[CLAUDE.md:1-10]()\n\n### Architecture\n\nThe server transforms the Notion REST API into an MCP-compatible interface:\n\n```mermaid\ngraph TD\n A[\"scripts/notion-openapi.json
OpenAPI 3.1.0 Spec\"] --> B[\"OpenAPIToMCPConverter\"]\n B --> C[\"MCP Tools
22 Tools Generated\"]\n C --> D[\"MCPProxy.setupHandlers()\"]\n D --> E[\"HttpClient
API Execution\"]\n E --> F[\"Notion API
https://api.notion.com\"]\n```\n\n### Tool Generation Flow\n\n| Step | Component | Description |\n|------|-----------|-------------|\n| 1 | OpenAPI Spec | Iterates all paths and operations |\n| 2 | Operation → Tool | Each operationId becomes a tool name |\n| 3 | Parameters | Converted to `inputSchema` |\n| 4 | Response | Converted to `returnSchema` |\n| 5 | Registration | `MCPProxy.setupHandlers()` registers with SDK |\n\n资料来源：[CLAUDE.md:32-38]()\n\n## Prerequisites\n\nBefore getting started, ensure you have:\n\n- **Node.js** 18+ (for native `Headers` support)\n- **npm** or **yarn** package manager\n- A **Notion integration** with an API token\n- Access to Notion pages you want the integration to access\n\n资料来源：[src/openapi-mcp-server/client/polyfill-headers.ts:1-5]()\n\n## Installation\n\n### Option 1: Using npm (Recommended)\n\nRun the server directly with `npx`:\n\n```bash\nnpx -y @notionhq/notion-mcp-server\n```\n\n资料来源：[README.md:1-5]()\n\n### Option 2: Using Docker\n\n#### Option 2a: Official Docker Hub Image\n\n```bash\ndocker run --rm -i \\\n -e NOTION_TOKEN=ntn_**** \\\n mcp/notion\n```\n\n#### Option 2b: Build Locally\n\n```bash\ndocker compose build\ndocker run --rm -i \\\n -e NOTION_TOKEN=ntn_**** \\\n notion-mcp-server\n```\n\n资料来源：[README.md:2-25]()\n\n### Option 3: Local Development\n\n```bash\ngit clone https://github.com/makenotion/notion-mcp-server.git\ncd notion-mcp-server\nnpm install\n```\n\n资料来源：[package.json:1-20]()\n\n## Configuration\n\n### Step 1: Create a Notion Integration\n\n1. Go to [https://www.notion.so/profile/integrations](https://www.notion.so/profile/integrations)\n2. Create a new **internal** integration or select an existing one\n3. Copy the integration token (starts with `ntn_`)\n\n资料来源：[README.md:1-8]()\n\n### Step 2: Grant Page Access\n\nFor each Notion page you want the integration to access:\n\n1. Open the target page\n2. Click the **three dots menu** (⋯)\n3. Select **\"Connect to integration\"**\n\n资料来源：[README.md:1-5]()\n\n### Step 3: Configure Your MCP Client\n\n#### Cursor & Claude Desktop\n\nAdd to `.cursor/mcp.json` or `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n#### Zed\n\nAdd to `settings.json`:\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\"}\"\n }\n },\n \"settings\": {}\n }\n }\n}\n```\n\n#### GitHub Copilot CLI\n\n```bash\n/mcp add\n```\n\nOr edit `~/.copilot/mcp-config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:1-70]()\n\n## Authentication\n\n### Environment Variables\n\n| Variable | Description | Priority |\n|----------|-------------|----------|\n| `NOTION_TOKEN` | Integration token (recommended) | Primary |\n| `OPENAPI_MCP_HEADERS` | JSON string with custom headers | Alternative |\n| `AUTH_TOKEN` | Bearer token for HTTP transport | Lower |\n\n资料来源：[scripts/start-server.ts:1-30]()\n\n### HTTP Transport Authentication\n\nWhen using the Streamable HTTP transport, bearer token authentication is required:\n\n```bash\n# Auto-generated token (development only)\nnpx @notionhq/notion-mcp-server --transport http\n\n# Custom token via CLI (recommended for production)\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n\n# Custom token via environment variable\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq/notion-mcp-server --transport http\n```\n\nThe `--auth-token` CLI argument takes precedence over the `AUTH_TOKEN` environment variable.\n\n资料来源：[scripts/start-server.ts:1-35]()\n\n### Making HTTP Requests\n\nAll requests must include the bearer token:\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n资料来源：[README.md:1-15]()\n\n## Command Line Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--transport ` | Transport type: `stdio` or `http` | `stdio` |\n| `--port ` | Port for HTTP server | `3000` |\n| `--auth-token ` | Bearer token for HTTP authentication | Auto-generated |\n| `--disable-auth` | Disable authentication for HTTP transport | `false` |\n| `--help`, `-h` | Show help message | - |\n\n资料来源：[scripts/start-server.ts:1-25]()\n\n### Usage Examples\n\n```bash\n# Default stdio transport\nnotion-mcp-server\n\n# Explicit stdio transport\nnotion-mcp-server --transport stdio\n\n# HTTP transport with custom port\nnotion-mcp-server --transport http --port 8080\n\n# HTTP transport with custom auth token\nnotion-mcp-server --transport http --auth-token \"my-secret\"\n```\n\n## Available Tools\n\nThe server exposes 22 MCP tools auto-generated from the Notion API. Key tools include:\n\n| Tool | Description | Version Change |\n|------|-------------|----------------|\n| `query-data-source` | Query a data source with filters and sorts | **New in v2.0** |\n| `retrieve-a-data-source` | Get metadata and schema for a data source | **New in v2.0** |\n| `create-a-data-source` | Create a new data source | **New in v2.0** |\n| `update-a-data-source` | Update data source properties | **New in v2.0** |\n| `move-page` | Move a page to a different parent | **New in v2.0** |\n| `list-data-source-templates` | List available templates in a data source | **New in v2.0** |\n| `retrieve-a-database` | Get database metadata including data source IDs | **New in v2.0** |\n| `search` | Search pages and data sources | Updated filter values |\n\n> **Note:** In v2.0.0, `database_id` parameters changed to `data_source_id` for data source operations.\n\n资料来源：[CLAUDE.md:1-20]()\n\n## Development\n\n### Build & Test\n\n```bash\nnpm run build # TypeScript compilation + CLI bundling\nnpm test # Run vitest tests\nnpm run dev # Start dev server with hot reload\n```\n\n### Testing Local Changes in Cursor\n\n1. Run `npm link` from repository root to create a machine-global symlink\n2. Add to Cursor's `mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n3. **Cleanup:** Run `npm unlink` from repository root\n\n### Publish\n\n```bash\nnpm login\nnpm publish --access public\n```\n\n资料来源：[CLAUDE.md:1-40]()\n\n## Example Usage\n\n### Natural Language Examples\n\n| Instruction | Operations |\n|-------------|------------|\n| Comment \"Hello MCP\" on page \"Getting started\" | `search` → `create-a-comment` |\n| Add a page titled \"Notion MCP\" to page \"Development\" | `search` → `create-a-page` |\n| Get the content of page `1a6b35e6e67f802fa7e1d27686f017f2` | `retrieve-a-block-children` |\n\nThe AI will automatically plan the correct sequence of API calls to accomplish the task.\n\n资料来源：[README.md:1-20]()\n\n## Parameter Handling\n\nThe MCP proxy automatically deserializes JSON-string parameters to support nested objects and arrays:\n\n```mermaid\ngraph LR\n A[\"String: '{\\\"key\\\":\\\"value\\\"}'\"] --> B[\"deserializeParams()\"]\n B --> C[\"Object: {key: 'value'}\"]\n \n D[\"Array: ['[1,2,3]']\"] --> B\n B --> E[\"Array: [1, 2, 3]\"]\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:1-60]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| \"No base URL found\" | Ensure OpenAPI spec has a valid server URL |\n| Authentication errors | Verify `NOTION_TOKEN` is set correctly |\n| Page access denied | Connect the integration to the target page in Notion |\n| Port already in use | Use `--port` to specify a different port |\n\n### Node.js Version\n\nThe server requires Node.js 18+ for native `Headers` class support. A polyfill is available for older versions.\n\n资料来源：[src/openapi-mcp-server/client/polyfill-headers.ts:1-5]()\n\n## Next Steps\n\n- Review the [CLAUDE.md](CLAUDE.md) for architecture details\n- Explore the [OpenAPI specification](scripts/notion-openapi.json) for all available endpoints\n- Check the [repository issues](https://github.com/makenotion/notion-mcp-server/issues) for known limitations\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Transport Layers](#page-transport-layers), [MCP Proxy Implementation](#page-mcp-proxy), [Available MCP Tools](#page-available-tools)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/openapi-mcp-server/index.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/index.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/auth/index.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/index.ts)\n- [src/openapi-mcp-server/auth/types.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/types.ts)\n- [src/openapi-mcp-server/auth/template.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/template.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n
\n\n# System Architecture\n\n## Overview\n\nThe Notion MCP Server is an official Model Context Protocol (MCP) server implementation that exposes the Notion API as MCP tools. The server automatically generates MCP tools from an OpenAPI 3.1.0 specification, enabling AI assistants to interact with Notion workspaces through standardized MCP protocols.\n\n资料来源：[CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n## High-Level Architecture\n\nThe system follows a layered architecture where the OpenAPI specification serves as the single source of truth for tool definitions. Tools are auto-generated from the spec without requiring manual code changes for new endpoints.\n\n```mermaid\ngraph TD\n A[scripts/notion-openapi.json
OpenAPI 3.1.0 Spec] --> B[OpenAPIToMCPConverter]\n B --> C[MCPProxy]\n C --> D[MCP SDK]\n A --> E[HttpClient]\n E --> F[Notion API v1]\n \n B -.->|Converts to| G[MCPTools]\n C -.->|Registers| G\n```\n\n资料来源：[CLAUDE.md:4-10](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n## Core Components\n\n### Component Architecture Table\n\n| Component | File Path | Responsibility |\n|-----------|-----------|----------------|\n| OpenAPI Specification | `scripts/notion-openapi.json` | Single source of truth for all API endpoints and schemas |\n| Server Entry Point | `src/init-server.ts` | Loads spec, creates MCPProxy instance |\n| OpenAPI Parser | `src/openapi-mcp-server/openapi/parser.ts` | Converts OpenAPI → MCP tool definitions |\n| MCP Proxy | `src/openapi-mcp-server/mcp/proxy.ts` | Tool registration and request handling |\n| HTTP Client | `src/openapi-mcp-server/client/http-client.ts` | Executes Notion API calls |\n| Auth Module | `src/openapi-mcp-server/auth/` | Authentication and header management |\n| Server CLI | `scripts/start-server.ts` | Transport layer initialization |\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts) \n资料来源：[src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n\n### OpenAPI to MCP Converter\n\nThe `OpenAPIToMCPConverter` class in `parser.ts` handles the transformation of OpenAPI operations into MCP-compatible tool definitions.\n\n```typescript\nconvertToMCPTools(): {\n tools: Record\n openApiLookup: Record\n zip: Record\n}\n```\n\nThe conversion process:\n\n1. Iterates all paths and operations from the OpenAPI spec\n2. Extracts operation parameters and requestBody schemas\n3. Generates JSON Schema for input validation\n4. Extracts response schemas for return types\n5. Creates MCP tool definitions with operationId as tool name\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:75-150](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n\n### MCP Proxy\n\nThe `MCPProxy` class manages tool registration and execution through the MCP SDK:\n\n```typescript\nclass MCPProxy {\n constructor(openApiSpec: OpenAPIV3.Document)\n private setupHandlers(): void\n private truncateToolName(name: string): string\n private operationIdToTitle(operationId: string): string\n}\n```\n\nKey responsibilities:\n\n- **Tool Registration**: Uses `ListToolsRequestSchema` to expose available tools\n- **Tool Execution**: Uses `CallToolRequestSchema` to handle tool invocations\n- **Parameter Deserialization**: Handles JSON string parsing for complex parameters\n- **Annotation**: Marks tools with `readOnlyHint` or `destructiveHint` based on HTTP method\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:60-120](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n\n## HTTP Client Architecture\n\n### Request Execution Flow\n\n```mermaid\ngraph LR\n A[Tool Request] --> B[MCPProxy]\n B --> C[Parameter Processing]\n C --> D[Path/Query Separation]\n D --> E[HttpClient.operationFn]\n E --> F[Axios HTTP Call]\n F --> G[Notion API]\n G --> F\n F --> H[Response Headers]\n H --> I[MCPToolResult]\n```\n\nThe HTTP client handles:\n\n| Responsibility | Implementation |\n|----------------|----------------|\n| Base URL Configuration | Configured via OpenAPI spec server definition |\n| Header Management | Merges auth headers with operation-specific headers |\n| Parameter Routing | Separates path/query params from body params |\n| Form Data Support | Detects and sets appropriate Content-Type headers |\n| Response Conversion | Transforms Axios headers to standard Headers object |\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:50-100](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n\n### Parameter Processing\n\n```typescript\n// Path and query parameters are extracted to urlParameters\nif (param.in === 'path' || param.in === 'query') {\n if (params[param.name] !== undefined) {\n urlParameters[param.name] = params[param.name]\n }\n}\n\n// Body parameters remain separate for request body\n// Form data uses multipart encoding\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:30-45](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n\n## Authentication System\n\n### Authentication Architecture\n\n```mermaid\ngraph TD\n A[Environment Variables] --> B[Auth Module]\n B --> C{Header Type}\n C -->|NOTION_TOKEN| D[Bearer Token]\n C -->|OPENAPI_MCP_HEADERS| E[Raw JSON Headers]\n D --> F[Authorization Header]\n E --> F\n F --> G[HttpClient Headers]\n```\n\n### Auth Module Structure\n\nThe authentication system is split into three modules:\n\n| Module | Purpose |\n|--------|---------|\n| `auth/types.ts` | TypeScript interfaces for auth configuration |\n| `auth/template.ts` | Header template definitions and validation |\n| `auth/index.ts` | Main export combining auth functionality |\n\n资料来源：[src/openapi-mcp-server/auth/index.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/index.ts) \n资料来源：[src/openapi-mcp-server/auth/types.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/types.ts)\n\n### Authentication Methods\n\nThe server supports two authentication approaches:\n\n| Method | Environment Variable | Format |\n|--------|---------------------|--------|\n| Simple Token | `NOTION_TOKEN` | `ntn_****` integration token |\n| Advanced Headers | `OPENAPI_MCP_HEADERS` | JSON with Authorization and Notion-Version |\n\n资料来源：[src/openapi-mcp-server/auth/template.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/template.ts)\n\n## Transport Layer Architecture\n\n### Supported Transports\n\n```mermaid\ngraph TD\n A[MCP Client] --> B{Transport Type}\n B -->|stdio| C[Standard I/O]\n B -->|http| D[Streamable HTTP]\n \n C --> E[scripts/start-server.ts]\n D --> E\n E --> F[MCPProxy]\n F --> G[Notion API]\n```\n\nThe server supports two transport mechanisms configured via CLI arguments:\n\n| Transport | Default | CLI Flag | Port |\n|-----------|---------|----------|------|\n| stdio | Yes | `--transport stdio` | N/A |\n| Streamable HTTP | No | `--transport http` | 3000 |\n\n资料来源：[scripts/start-server.ts:1-50](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n### HTTP Transport Security\n\nFor HTTP transport, bearer token authentication is required:\n\n```bash\n# Auto-generated token (development only)\nnpx @notionhq/notion-mcp-server --transport http\n\n# Custom token via CLI\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-token\"\n\n# Custom token via environment variable\nAUTH_TOKEN=\"your-token\" npx @notionhq/notion-mcp-server --transport http\n```\n\n资料来源：[scripts/start-server.ts:30-80](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Tool Naming Conventions\n\nTool names are derived from OpenAPI `operationId` with the following transformations:\n\n| Original operationId | Generated Tool Name |\n|---------------------|---------------------|\n| `retrieve-a-database` | `Retrieve-A-Database` |\n| `create-a-page` | `Create-A-Page` |\n| `search` | `Search` |\n\n**Rules:**\n- Names are truncated to 64 characters maximum\n- Converted to Title Case for display\n- Prefixed with parent tool name and hyphen when multiple methods exist\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:140-160](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n\n## Schema Conversion\n\n### OpenAPI to JSON Schema Mapping\n\nThe `convertOpenApiSchemaToJsonSchema` method handles complex schema transformations:\n\n| OpenAPI Feature | JSON Schema Output | Notes |\n|-----------------|-------------------|-------|\n| `format: binary` | `format: uri-reference` | For file path handling |\n| `type: object` | `type: object` | Includes properties and additionalProperties |\n| `type: array` | `type: array` | Converts items recursively |\n| `oneOf/anyOf/allOf` | `oneOf/anyOf/allOf` | Preserves discriminator info |\n| `enum` | `enum` | Preserves allowed values |\n| `const` | `const` | Important for discriminator keys |\n| `default` | `default` | Provides fallback values |\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:20-80](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n\n## Server Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant CLI as scripts/start-server.ts\n participant Init as src/init-server.ts\n participant Proxy as MCPProxy\n participant Auth as Auth Module\n \n CLI->>Init: Loads notion-openapi.json\n Init->>Auth: parseHeadersFromEnv()\n Auth-->>Init: Headers configuration\n Init->>Proxy: new MCPProxy(spec, headers)\n Proxy->>Proxy: convertToMCPTools()\n Proxy->>Proxy: setupHandlers()\n Init->>CLI: Configured server\n CLI->>CLI: Start transport (stdio/http)\n```\n\n资料来源：[src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n\n## API Version Management\n\nThe server uses Notion API version `2025-09-03` (Data Source Edition):\n\n| Endpoint Type | Pattern | Description |\n|---------------|---------|-------------|\n| Traditional | `/v1/databases/{database_id}` | Classic database operations |\n| Data Source | `/v1/data_sources/{data_source_id}` | New data source endpoints |\n\n资料来源：[CLAUDE.md:18-20](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n## Configuration Options\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `NOTION_TOKEN` | Yes (recommended) | Notion integration token |\n| `OPENAPI_MCP_HEADERS` | No | JSON string with custom headers |\n| `AUTH_TOKEN` | No | Bearer token for HTTP transport |\n| `PORT` | No | HTTP server port (default: 3000) |\n\n### CLI Arguments\n\n| Argument | Type | Default | Description |\n|----------|------|---------|-------------|\n| `--transport` | string | stdio | Transport type |\n| `--port` | number | 3000 | HTTP server port |\n| `--auth-token` | string | auto-generated | Bearer token |\n| `--disable-auth` | flag | false | Disable HTTP auth |\n| `--help` | flag | - | Show help message |\n\n资料来源：[scripts/start-server.ts:5-40](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n---\n\n\n\n## Transport Layers\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Authentication System](#page-authentication)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n
\n\n# Transport Layers\n\nThe Notion MCP Server supports two distinct transport mechanisms for communication between AI clients and the server: **stdio** (Standard Input/Output) and **Streamable HTTP**. These transport layers define how MCP protocol messages are exchanged, authentication is handled, and the server exposes its capabilities to clients.\n\n## Overview\n\nTransport layers in the MCP (Model Context Protocol) serve as the communication backbone between AI assistants and the server. The Notion MCP Server abstracts the underlying transport details, allowing clients to choose the mode that best fits their environment.\n\n```mermaid\ngraph TD\n subgraph \"Transport Modes\"\n A[\"stdio Transport
(Default)\"] \n B[\"Streamable HTTP Transport\"]\n end\n \n subgraph \"Client Types\"\n C[\"Cursor\"]\n D[\"Claude Desktop\"]\n E[\"Zed Editor\"]\n F[\"GitHub Copilot CLI\"]\n end\n \n A --> C\n A --> D\n B --> E\n B --> F\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Transport Types\n\n### stdio Transport (Default)\n\nThe stdio transport is the default mode for the Notion MCP Server. It uses standard input and output streams for communication, making it ideal for local development and integration with desktop AI clients.\n\n**Characteristics:**\n\n- Bidirectional JSON-RPC communication via stdin/stdout\n- No network binding required\n- Suitable for local MCP clients\n- Default mode when no transport is specified\n\n**Usage:**\n\n```bash\n# Default stdio mode\nnotion-mcp-server\n\n# Explicit stdio mode\nnotion-mcp-server --transport stdio\n```\n\n资料来源：[scripts/start-server.ts:1-45](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n### Streamable HTTP Transport\n\nThe HTTP transport enables network-based communication, allowing remote or distributed clients to connect to the MCP server. This mode requires explicit configuration and includes built-in bearer token authentication.\n\n**Characteristics:**\n\n- HTTP-based protocol over TCP/IP\n- Session-based communication with `mcp-session-id` header\n- Bearer token authentication (required unless disabled)\n- Runs on configurable port (default: 3000)\n- Endpoint available at `/mcp`\n\n**Basic Usage:**\n\n```bash\n# Default HTTP on port 3000\nnotion-mcp-server --transport http\n\n# Custom port\nnotion-mcp-server --transport http --port 8080\n\n# With custom auth token\nnotion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\n资料来源：[scripts/start-server.ts:1-50](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Command Line Options\n\nThe server accepts the following command line arguments to configure transport behavior:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--transport ` | string | `stdio` | Transport type: `stdio` or `http` |\n| `--port ` | integer | `3000` | HTTP server port (only for HTTP transport) |\n| `--auth-token ` | string | auto-generated | Bearer token for HTTP authentication |\n| `--disable-auth` | flag | `false` | Disable bearer token authentication |\n| `--help`, `-h` | flag | - | Display help message |\n\n**Precedence:** Command line arguments take precedence over environment variables.\n\n资料来源：[scripts/start-server.ts:10-35](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Authentication\n\n### Environment Variables\n\nThe server respects the following environment variables for authentication configuration:\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `NOTION_TOKEN` | Notion integration secret token | Yes (for API calls) |\n| `OPENAPI_MCP_HEADERS` | JSON string with custom headers | Alternative to NOTION_TOKEN |\n| `AUTH_TOKEN` | Bearer token for HTTP transport | For HTTP transport |\n\n**Header Format for OPENAPI_MCP_HEADERS:**\n\n```json\n{\n \"Authorization\": \"Bearer ntn_****\",\n \"Notion-Version\": \"2025-09-03\"\n}\n```\n\n### HTTP Transport Authentication Modes\n\n#### Auto-Generated Token (Development Only)\n\nWhen running without explicit authentication configuration, the server generates a secure random token:\n\n```bash\nnpx notion-mcp-server --transport http\n```\n\nOutput:\n```\nGenerated auth token: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\nUse this token in the Authorization header: Bearer a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\n```\n\n#### Custom Token via Command Line (Production)\n\n```bash\nnotion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\n#### Custom Token via Environment Variable\n\n```bash\nAUTH_TOKEN=\"your-secret-token\" notion-mcp-server --transport http\n```\n\n#### Disabling Authentication\n\n```bash\nnotion-mcp-server --transport http --disable-auth\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## HTTP Request Format\n\nWhen using the Streamable HTTP transport, all requests must include specific headers:\n\n### Required Headers\n\n| Header | Value | Description |\n|--------|-------|-------------|\n| `Authorization` | `Bearer ` | Bearer token for authentication |\n| `Content-Type` | `application/json` | Request content type |\n| `mcp-session-id` | `` | MCP session identifier |\n\n### Example Request\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n**Server Endpoint:** `http://0.0.0.0:/mcp`\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Architecture\n\n### Component Flow\n\n```mermaid\ngraph TD\n subgraph \"Entry Point\"\n A[\"scripts/start-server.ts
Parse CLI arguments\"]\n end\n \n subgraph \"Initialization\"\n B[\"src/init-server.ts
Load OpenAPI spec\"]\n C[\"Create MCPProxy instance\"]\n end\n \n subgraph \"Transport Layer\"\n D[\"Transport Selection
stdio vs http\"]\n end\n \n subgraph \"MCP Server\"\n E[\"MCPProxy.setupHandlers()
Register tools\"]\n F[\"OpenAPIToMCPConverter
Convert OpenAPI → MCP tools\"]\n end\n \n subgraph \"HTTP Client\"\n G[\"HttpClient
Execute Notion API calls\"]\n end\n \n A --> B\n B --> C\n C --> D\n D --> E\n E --> F\n F --> G\n \n style D fill:#f9f,stroke:#333\n```\n\n资料来源：[CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n### Request Processing Flow (HTTP Transport)\n\n```mermaid\nsequenceDiagram\n participant Client\n participant HTTPServer as HTTP Server
(Express)\n participant MCPServer as MCP Server
(MCPProxy)\n participant HTTPClient as HttpClient\n participant NotionAPI as Notion API\n \n Client->>HTTPServer: HTTP Request with Auth Header\n HTTPServer->>HTTPServer: Validate Bearer Token\n alt Token Valid\n HTTPServer->>MCPServer: Forward MCP Request\n MCPServer->>HTTPClient: Execute Tool Call\n HTTPClient->>NotionAPI: API Request\n NotionAPI-->>HTTPClient: API Response\n HTTPClient-->>MCPServer: Structured Response\n MCPServer-->>HTTPServer: MCP Response\n HTTPServer-->>Client: HTTP Response\n else Token Invalid\n HTTPServer-->>Client: 401 Unauthorized\n end\n```\n\n## Client Configuration Examples\n\n### Cursor & Claude Desktop\n\n**stdio Transport:**\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n**HTTP Transport:**\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\",\n \"AUTH_TOKEN\": \"your-auth-token\"\n }\n }\n }\n}\n```\n\n### Zed Editor\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\" }\"\n }\n },\n \"settings\": {}\n }\n }\n}\n```\n\n### GitHub Copilot CLI\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Docker Deployment\n\n### Option 1: Official Docker Hub Image\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN\",\n \"mcp/notion\"\n ],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### Option 2: Local Docker Build\n\n```bash\ndocker compose build\n```\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN=ntn_****\",\n \"notion-mcp-server\"\n ]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Local Development Testing\n\nFor testing changes locally in development environments:\n\n1. Run `npm link` from repository root to create a machine-global symlink\n2. Add configuration to client's `mcp.json`\n3. Run `npm unlink` for cleanup\n\n```bash\nnpm link\n```\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## HTTP Client Implementation\n\nThe internal HTTP client handles the actual API communication with Notion's backend:\n\n**Key Responsibilities:**\n\n- Base URL configuration from OpenAPI spec\n- Request header management\n- Form data handling for file uploads\n- Response header conversion to standard `Headers` object\n- URL parameter vs body parameter routing\n\n```typescript\n// Parameter routing logic\nif (param.in === 'path' || param.in === 'query') {\n urlParameters[param.name] = params[param.name]\n}\n\n// Body parameters for POST/PUT requests\nif (!operation.requestBody && !formData) {\n urlParameters[key] = bodyParams[key]\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-50](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n\n## Choosing a Transport\n\n| Use Case | Recommended Transport | Reason |\n|----------|----------------------|--------|\n| Local desktop AI client | stdio | Simple, no network required |\n| Remote/distributed clients | HTTP | Network accessible |\n| Development/testing | stdio or HTTP (auto-token) | Flexibility |\n| Production deployment | HTTP with custom token | Security and scalability |\n| Docker containers | HTTP | Container networking |\n| CI/CD pipelines | stdio | Ephemeral execution |\n\n## Summary\n\nThe Notion MCP Server provides two transport mechanisms optimized for different deployment scenarios. The **stdio transport** offers simplicity for local use, while the **Streamable HTTP transport** enables networked deployments with built-in authentication. Both transports leverage the same underlying MCP tool registration and HTTP client infrastructure, ensuring consistent behavior regardless of the communication method chosen.\n\n---\n\n\n\n## MCP Proxy Implementation\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Available MCP Tools](#page-available-tools)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/init-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n
\n\n# MCP Proxy Implementation\n\n## Overview\n\nThe MCP Proxy is the core component of the Notion MCP Server that bridges the gap between the Notion OpenAPI specification and the Model Context Protocol (MCP). It transforms REST API endpoints defined in the OpenAPI spec into executable MCP tools that AI assistants can invoke.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[OpenAPI Spec
scripts/notion-openapi.json] --> B[OpenAPIToMCPConverter]\n B --> C[MCP Tools Generation]\n C --> D[MCPProxy]\n D --> E[MCP SDK Server]\n \n F[HTTP Client] --> G[Notion API]\n D --> F\n \n H[MCP Client
Claude/Cursor] --> E\n E --> H\n \n I[Tool Call Request] --> E\n E --> F\n F --> G\n G --> J[API Response]\n J --> E\n E --> K[Tool Result]\n K --> H\n```\n\n## Core Components\n\n### MCPProxy Class\n\nThe `MCPProxy` class serves as the central orchestration layer. It initializes the MCP server, converts OpenAPI specifications into MCP tools, and handles all tool execution requests.\n\n**File Location:** `src/openapi-mcp-server/mcp/proxy.ts`\n\n#### Constructor Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `name` | `string` | Display name for the MCP server |\n| `openApiSpec` | `OpenAPIV3.Document` | Parsed OpenAPI 3.1.0 specification |\n| `baseUrl` | `string \\| undefined` | Optional base URL override |\n| `openApiSpecPath` | `string` | Path to the OpenAPI spec file |\n\n#### Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant MCPProxy\n participant Converter\n participant HttpClient\n participant MCPSDK\n\n Client->>MCPProxy: new MCPProxy(name, spec)\n MCPProxy->>HttpClient: Create HttpClient instance\n MCPProxy->>Converter: Create OpenAPIToMCPConverter\n Converter->>Converter: convertToMCPTools()\n Converter-->>MCPProxy: tools, openApiLookup\n MCPProxy->>MCPSDK: setupHandlers()\n MCPSDK-->>Client: Server ready\n```\n\n### Tool Registration\n\nThe `setupHandlers()` method registers two primary request handlers with the MCP SDK:\n\n#### ListToolsRequestHandler\n\nReturns all available MCP tools to clients. For each operation in the OpenAPI spec:\n\n1. Iterates through all tools and their methods\n2. Constructs tool names using pattern: `{toolName}-{methodName}`\n3. Truncates names to 64 characters for MCP compliance\n4. Determines read/write behavior based on HTTP method\n\n**Tool Naming Convention:**\n\n```typescript\nconst toolNameWithMethod = `${toolName}-${method.name}`;\nconst truncatedToolName = this.truncateToolName(toolNameWithMethod);\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:52-66]()\n\n#### CallToolRequestHandler\n\nProcesses incoming tool execution requests:\n\n1. Extracts tool name from request\n2. Looks up operation in `openApiLookup` map\n3. Executes HTTP request via `HttpClient`\n4. Returns formatted response to MCP client\n\n### Tool Annotations\n\nEach tool includes metadata annotations:\n\n| Annotation | Type | Description |\n|------------|------|-------------|\n| `title` | `string` | Human-readable operation title |\n| `readOnlyHint` | `boolean` | `true` for GET requests |\n| `destructiveHint` | `boolean` | `true` for non-GET requests |\n\n```typescript\nannotations: {\n title: this.operationIdToTitle(method.name),\n ...(isReadOnly\n ? { readOnlyHint: true }\n : { destructiveHint: true }),\n},\n```\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts:60-67]()\n\n## HTTP Client Integration\n\nThe `HttpClient` class handles all outbound HTTP communication with the Notion API.\n\n### Configuration\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `baseUrl` | `string` | Notion API base URL |\n| `headers` | `Record` | Default request headers |\n\n### Request Processing\n\n1. **Parameter Extraction**: Separates path, query, and body parameters\n2. **Form Data Handling**: Detects `multipart/form-data` content types\n3. **Header Management**: Sets appropriate Content-Type headers\n4. **Response Conversion**: Transforms axios responses to standard Headers objects\n\n```typescript\nconst hasBody = Object.keys(bodyParams).length > 0\nconst headers = formData\n ? formData.getHeaders()\n : { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:70-76]()\n\n## OpenAPI to MCP Conversion\n\nThe `OpenAPIToMCPConverter` class transforms OpenAPI operations into MCP tool definitions.\n\n### Schema Conversion\n\nThe converter handles:\n\n- **Object types**: Properties, required fields, additionalProperties\n- **Binary formats**: Converts to URI-reference format for file handling\n- **Enumerations**: Preserves enum values\n- **Const values**: Supports oneOf discriminators\n- **Default values**: Includes default values in schemas\n\n### JSON Schema Mapping\n\n| OpenAPI Type | JSON Schema Type |\n|--------------|------------------|\n| `object` | `object` |\n| `array` | `array` |\n| `string` | `string` |\n| `integer` | `integer` |\n| `number` | `number` |\n| `boolean` | `boolean` |\n| `binary` | `uri-reference` |\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:45-72]()\n\n## Server Initialization\n\n### Entry Point\n\nThe server is initialized via `src/init-server.ts`:\n\n```mermaid\ngraph LR\n A[scripts/start-server.ts] --> B[src/init-server.ts]\n B --> C[loadOpenApiSpec]\n C --> D[Validate JSON Schema]\n D --> E[new MCPProxy]\n E --> F[Return proxy instance]\n```\n\n### Specification Loading\n\n1. Reads OpenAPI spec from filesystem\n2. Parses JSON content\n3. Overrides `baseUrl` if specified\n4. Validates against OpenAPI 3.1.0 schema\n\n```typescript\nexport async function initProxy(specPath: string, baseUrl: string | undefined) {\n const openApiSpec = await loadOpenApiSpec(specPath, baseUrl)\n const proxy = new MCPProxy('Notion API', openApiSpec)\n return proxy\n}\n```\n\n资料来源：[src/init-server.ts:43-48]()\n\n## Command Line Interface\n\nThe CLI entry point supports multiple transport modes and authentication options.\n\n### Supported Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--transport` | `stdio` \\| `http` | `stdio` | Transport type |\n| `--port` | `number` | `3000` | HTTP server port |\n| `--auth-token` | `string` | auto-generated | Bearer token for HTTP auth |\n| `--disable-auth` | `flag` | `false` | Disable authentication |\n| `--help`, `-h` | `flag` | - | Show help message |\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `NOTION_TOKEN` | Notion integration token |\n| `OPENAPI_MCP_HEADERS` | JSON string with API headers |\n| `AUTH_TOKEN` | Bearer token for HTTP transport |\n\n资料来源：[scripts/start-server.ts:1-30]()\n\n## Tool Execution Workflow\n\n```mermaid\nsequenceDiagram\n participant AI as AI Assistant\n participant MCPSDK as MCP SDK\n participant Proxy as MCPProxy\n participant Client as HttpClient\n participant API as Notion API\n\n AI->>MCPSDK: list_tools()\n MCPSDK-->>AI: Available tools\n \n AI->>MCPSDK: call_tool(\"retrieve-page-123\")\n MCPSDK->>Proxy: execute(toolName, params)\n \n alt Tool Lookup\n Proxy->>Proxy: openApiLookup[toolName]\n Proxy-->>Proxy: Operation found\n end\n \n Proxy->>Client: execute(operationId, params)\n \n Client->>API: HTTP Request\n API-->>Client: API Response\n \n Client-->>Proxy: Formatted response\n Proxy-->>MCPSDK: Tool result\n MCPSDK-->>AI: Success/Error\n```\n\n## Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@modelcontextprotocol/sdk` | `^1.25.1` | MCP protocol implementation |\n| `axios` | `^1.8.4` | HTTP client |\n| `express` | `^4.21.2` | HTTP server transport |\n| `openapi-client-axios` | `^7.5.5` | OpenAPI client generation |\n| `zod` | `3.24.1` | Schema validation |\n\n资料来源：[package.json:22-40]()\n\n## Key Implementation Patterns\n\n### Tool Name Transformation\n\nTool names are generated from OpenAPI `operationId` values:\n\n1. **Original**: `retrieve-a-database`\n2. **Transformation**: Convert to title case → `RetrieveADatabase`\n3. **Truncation**: Limit to 64 characters\n\n### Request Body Handling\n\n```typescript\n// If no requestBody defined, promote body params to query params\nif (!operation.requestBody && !formData) {\n for (const key in bodyParams) {\n if (bodyParams[key] !== undefined) {\n urlParameters[key] = bodyParams[key]\n delete bodyParams[key]\n }\n }\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:50-56]()\n\n### Header Parsing\n\nHeaders can be configured via the `OPENAPI_MCP_HEADERS` environment variable:\n\n```typescript\nprivate parseHeadersFromEnv(): Record {\n const headersStr = process.env.OPENAPI_MCP_HEADERS\n if (headersStr) {\n try {\n return JSON.parse(headersStr)\n } catch {\n console.error('Failed to parse OPENAPI_MCP_HEADERS')\n }\n }\n return {}\n}\n```\n\n## Error Handling\n\nThe proxy implements robust error handling at multiple levels:\n\n| Error Type | Handling |\n|------------|----------|\n| Invalid operation | `Error: Operation {id} not found` |\n| HTTP errors | Propagated from axios |\n| JSON parse errors | Console error + process exit |\n| Spec validation | `ValidationError` with details |\n\n## Performance Considerations\n\n1. **Tool Lookup**: O(1) lookup via `openApiLookup` Map\n2. **Lazy Loading**: Operations are loaded once at initialization\n3. **Connection Pooling**: Axios manages HTTP connection reuse\n4. **Schema Caching**: Resolved references cached in memory\n\n---\n\n\n\n## Available MCP Tools\n\n### 相关页面\n\n相关主题：[Data Sources (v2.0.0 Breaking Changes)](#page-data-sources-v2), [System Architecture](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/notion-openapi.json](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/notion-openapi.json)\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n
\n\n# Available MCP Tools\n\n## Overview\n\nThe Notion MCP Server exposes the Notion API as MCP (Model Context Protocol) tools, enabling AI clients to interact with Notion workspaces programmatically. Each tool corresponds to a specific Notion API endpoint and is auto-generated from the OpenAPI specification at `scripts/notion-openapi.json` 资料来源：[CLAUDE.md:1-12]()\n\nThe MCP tools serve as the bridge between AI assistants and Notion's API, providing capabilities to:\n\n- Search and retrieve pages and databases\n- Create, update, and manage content\n- Work with comments and user information\n- Query data sources with filters and sorting\n\n## Architecture\n\nThe tool generation and execution follows a clear architectural flow:\n\n```mermaid\ngraph TD\n A[scripts/notion-openapi.json
OpenAPI 3.1.0 Spec] --> B[OpenAPIToMCPConverter]\n B --> C[MCP Tools Registry]\n C --> D[AI Client]\n D --> E[Tool Invocation]\n E --> F[deserializeParams]\n F --> G[HttpClient.executeOperation]\n G --> H[Notion API]\n \n subgraph \"src/openapi-mcp-server/\"\n B\n F\n G\n end\n```\n\n### Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| OpenAPI Spec | `scripts/notion-openapi.json` | Source of truth for all tools |\n| Parser | `src/openapi-mcp-server/openapi/parser.ts` | Converts OpenAPI to MCP tools |\n| Proxy | `src/openapi-mcp-server/mcp/proxy.ts` | Registers tools with MCP SDK |\n| HTTP Client | `src/openapi-mcp-server/client/http-client.ts` | Executes API calls |\n\n资料来源：[CLAUDE.md:15-22]()\n\n## Tool Generation Flow\n\nThe tool generation process consists of five steps:\n\n1. **`OpenAPIToMCPConverter.convertToMCPTools()`** iterates over all paths and operations in the OpenAPI spec\n2. Each operation becomes an MCP tool with name derived from `operationId`\n3. Parameters and requestBody are converted to `inputSchema`\n4. Response schema becomes `returnSchema`\n5. **`MCPProxy.setupHandlers()`** registers tools with the MCP SDK\n\n```mermaid\nsequenceDiagram\n participant Spec as OpenAPI Spec\n participant Parser as OpenAPIToMCPConverter\n participant Proxy as MCPProxy\n participant SDK as MCP SDK\n participant Client as AI Client\n \n Spec->>Parser: Load specification\n Parser->>Parser: convertToMCPTools()\n Parser->>Proxy: tools, openApiLookup\n Proxy->>SDK: registerToolHandlers()\n Client->>SDK: list_tools\n SDK->>Client: Available tools\n Client->>SDK: call_tool\n SDK->>Proxy: executeOperation\n```\n\n资料来源：[CLAUDE.md:24-31]()\n\n## Version 2.0.0 Breaking Changes\n\n**Version 2.0.0 migrates to the Notion API 2025-09-03** which introduces data sources as the primary abstraction for databases 资料来源：[README.md:1-50]()\n\n### Removed Tools (3)\n\n| Old Tool | Replacement |\n|----------|-------------|\n| `post-database-query` | `query-data-source` |\n| `update-a-database` | `update-a-data-source` |\n| `create-a-database` | `create-a-data-source` |\n\n### New Tools (7)\n\n| New Tool | Purpose |\n|----------|---------|\n| `query-data-source` | Query a data source (database) with filters and sorts |\n| `retrieve-a-data-source` | Get metadata and schema for a data source |\n| `update-a-data-source` | Update data source properties |\n| `create-a-data-source` | Create a new data source |\n| `list-data-source-templates` | List available templates in a data source |\n| `move-page` | Move a page to a different parent location |\n| `retrieve-a-database` | Get database metadata including its data source IDs |\n\n### Parameter Changes\n\n| Change Type | Old Parameter | New Parameter |\n|-------------|---------------|---------------|\n| Database ID | `database_id` | `data_source_id` |\n| Search Filter | `[\"page\", \"database\"]` | `[\"page\", \"data_source\"]` |\n\n资料来源：[README.md:1-50]()\n\n## Tool Naming Conventions\n\nTool names are derived directly from the OpenAPI `operationId`:\n\n- Example: `retrieve-a-database` becomes `RetrieveADatabase`\n- Names are truncated to 64 characters maximum\n- Converted to title case for display purposes\n\n```typescript\n// operationId: \"retrieve-a-database\"\n// Resulting tool name: \"RetrieveADatabase\"\nprivate operationIdToTitle(operationId: string): string {\n return operationId\n .split('-')\n .map(word => word.charAt(0).toUpperCase() + word.slice(1))\n .join('')\n .slice(0, 64);\n}\n```\n\n资料来源：[CLAUDE.md:33-34]()\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `NOTION_TOKEN` | Notion integration token (recommended) | Yes |\n| `OPENAPI_MCP_HEADERS` | JSON string with Notion API headers | Alternative |\n| `AUTH_TOKEN` | Bearer token for HTTP transport authentication | Optional |\n| `OPENAPI_MCP_HEADERS` | Custom headers for Notion API requests | Optional |\n\n资料来源：[README.md:1-50]()\n\n### Header Configuration Example\n\n```json\n{\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\"}\"\n}\n```\n\n## Parameter Handling\n\n### Deserialization Process\n\nThe MCP server handles a known issue with double-serialized JSON parameters (GitHub issue #176). When parameters arrive as stringified JSON objects or arrays, they are automatically deserialized:\n\n```typescript\nfunction deserializeParams(params: Record): Record {\n for (const [key, value] of Object.entries(params)) {\n if (typeof value === 'string') {\n const trimmed = value.trim();\n if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||\n (trimmed.startsWith('[') && trimmed.endsWith(']'))) {\n try {\n const parsed = JSON.parse(value);\n if (typeof parsed === 'object' && parsed !== null) {\n result[key] = Array.isArray(parsed)\n ? parsed\n : deserializeParams(parsed);\n }\n } catch { /* keep original string */ }\n }\n }\n }\n return result;\n}\n```\n\nThis function recursively processes nested objects and arrays to ensure proper parameter handling 资料来源：[src/openapi-mcp-server/mcp/proxy.ts:1-50]()\n\n### Schema Conversion\n\nThe `OpenAPIToMCPConverter` converts OpenAPI schemas to JSON Schema format for MCP tool definitions:\n\n- `type: string` with `format: binary` → converted to `format: uri-reference`\n- Handles `oneOf`, `anyOf`, `allOf` schema composition\n- Preserves `enum` values and `const` discriminators\n- Maintains `required` field arrays\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts:1-50]()\n\n## Example Usage\n\n### Search and Create\n\n```text\nComment \"Hello MCP\" on page \"Getting started\"\n```\n\nThe AI correctly plans two API calls:\n1. `v1/search` - Find the page \"Getting started\"\n2. `v1/comments` - Create the comment\n\n### Page Creation\n\n```text\nAdd a page titled \"Notion MCP\" to page \"Development\"\n```\n\n### Direct ID Reference\n\n```text\nGet the content of page 1a6b35e6e67f802fa7e1d27686f017f2\n```\n\n资料来源：[README.md:1-50]()\n\n## MCP Client Configuration\n\n### Cursor & Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### Zed\n\n```json\n{\n \"context_servers\": {\n \"notion-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"]\n },\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\"}\"\n }\n }\n }\n}\n```\n\n### GitHub Copilot CLI\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:1-50]()\n\n## HTTP Transport Authentication\n\nWhen using Streamable HTTP transport, bearer token authentication is required:\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\n### Authentication Options\n\n| Method | Priority | Use Case |\n|--------|----------|----------|\n| `--auth-token` CLI arg | Highest | Production |\n| `AUTH_TOKEN` env var | Medium | Production |\n| Auto-generated token | Lowest | Development only |\n\nAll requests must include the bearer token:\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n资料来源：[README.md:1-50]()\n\n## Error Handling\n\nThe MCP server provides structured error responses for HTTP errors:\n\n```typescript\nif (error instanceof HttpClientError) {\n const data = error.data?.response?.data ?? error.data ?? {};\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({ error: data }),\n },\n ],\n isError: true,\n };\n}\n```\n\nErrors are logged to console with descriptive messages for debugging 资料来源：[src/openapi-mcp-server/mcp/proxy.ts:100-130]()\n\n## Adding New Tools\n\nTo add new tools, only modify the OpenAPI specification at `scripts/notion-openapi.json`. No code changes are required elsewhere—tools are automatically generated from the spec when the server starts 资料来源：[CLAUDE.md:18-22]()\n\n### OpenAPI Specification\n\nThe server uses OpenAPI 3.1.0 specification with both traditional and new data source endpoints:\n\n| Endpoint Type | Path Pattern |\n|--------------|--------------|\n| Traditional | `/v1/databases/{database_id}` |\n| Data Source | `/v1/data_sources/{data_source_id}` |\n\n资料来源：[CLAUDE.md:44-47]()\n\n## Development\n\n### Build & Test Commands\n\n```bash\nnpm run build # TypeScript compilation + CLI bundling\nnpm test # Run vitest tests\nnpm run dev # Start dev server with hot reload\n```\n\n### Local Testing\n\n1. Run `npm link` from repository root to create a machine-global symlink\n2. Update your MCP client's configuration:\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_...\"\n }\n }\n }\n}\n```\n\n3. Cleanup with `npm unlink` when done\n\n资料来源：[README.md:1-50]()\n\n---\n\n\n\n## Data Sources (v2.0.0 Breaking Changes)\n\n### 相关页面\n\n相关主题：[Available MCP Tools](#page-available-tools)\n\n
\nRelated Source Files\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n- [src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n
\n\n# Data Sources (v2.0.0 Breaking Changes)\n\n## Overview\n\nVersion 2.0.0 of the Notion MCP Server introduces a fundamental architectural change by migrating to the **Notion API 2025-09-03**, which adopts **Data Sources** as the primary abstraction for databases. This represents a significant shift in how the MCP server interacts with Notion's database functionality.\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## What Are Data Sources?\n\nData Sources serve as a new abstraction layer that wraps traditional Notion databases. They provide enhanced metadata and schema capabilities that align with Notion's evolving platform architecture. The data source model maintains compatibility with existing database endpoints while introducing new functionality.\n\n资料来源：[CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\nThe Notion API 2025-09-03 version includes dual endpoint support:\n\n| Endpoint Type | Path Pattern | Purpose |\n|---------------|--------------|---------|\n| Traditional Database | `/v1/databases/{database_id}` | Legacy database operations |\n| New Data Source | `/v1/data_sources/{data_source_id}` | Modern data source operations |\n\n资料来源：[CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n## Breaking Changes Summary\n\n### Tools Removed\n\nThe following three tools have been **removed** and replaced by their data source equivalents:\n\n| Removed Tool | Replacement Tool | Purpose |\n|--------------|------------------|---------|\n| `post-database-query` | `query-data-source` | Query data source with filters and sorts |\n| `update-a-database` | `update-a-data-source` | Update data source properties |\n| `create-a-database` | `create-a-data-source` | Create a new data source |\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### New Tools Added\n\nSeven new tools have been introduced in version 2.0.0:\n\n| New Tool | Description |\n|----------|-------------|\n| `query-data-source` | Query a data source (database) with filters and sorts |\n| `retrieve-a-data-source` | Get metadata and schema for a data source |\n| `update-a-data-source` | Update data source properties |\n| `create-a-data-source` | Create a new data source |\n| `list-data-source-templates` | List available templates in a data source |\n| `move-page` | Move a page to a different parent location |\n| `retrieve-a-database` | Get database metadata including its data source IDs |\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Parameter Changes\n\n### Identifier Renaming\n\nAll database operations now use `data_source_id` instead of `database_id`:\n\n```typescript\n// Before (v1.x)\nparameters: {\n database_id: string;\n}\n\n// After (v2.0.0)\nparameters: {\n data_source_id: string;\n}\n```\n\n### Search Filter Values\n\nThe search operation filter values have been updated:\n\n| Previous Value | New Value |\n|----------------|-----------|\n| `\"database\"` | `\"data_source\"` |\n\n```typescript\n// Before (v1.x)\nfilter: {\n value: [\"page\", \"database\"];\n}\n\n// After (v2.0.0)\nfilter: {\n value: [\"page\", \"data_source\"];\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Page Creation Enhancement\n\nPage creation now supports both `page_id` and `database_id` parents for data sources:\n\n```typescript\ninterface CreatePageParameters {\n parent: {\n page_id?: string;\n database_id?: string; // Now includes database_id support\n };\n}\n```\n\n## Architecture Flow\n\n```mermaid\ngraph TD\n A[MCP Client Request] --> B[MCP Server]\n B --> C{Determine Operation Type}\n \n C -->|Database Operation| D[Database Endpoints]\n C -->|Data Source Operation| E[Data Source Endpoints]\n \n D --> F[/v1/databases/{database_id}]\n E --> G[/v1/data_sources/{data_source_id}]\n \n F --> H[Notion API 2025-09-03]\n G --> H\n \n H --> I[Response with Schema]\n I --> J[OpenAPI Parser]\n J --> K[MCP Tool Response]\n```\n\n## Migration Guide\n\n### Do I Need to Migrate?\n\n**No code changes required.** MCP tools are discovered automatically when the server starts. When you upgrade to v2.0.0, AI clients will automatically see the new tools.\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Automatic Discovery\n\nThe MCP server auto-generates tools from the OpenAPI specification located at `scripts/notion-openapi.json`. Tool generation follows this flow:\n\n```mermaid\ngraph LR\n A[scripts/notion-openapi.json] --> B[OpenAPIToMCPConverter]\n B --> C[convertToMCPTools]\n C --> D[MCP Tools Registry]\n D --> E[MCPProxy.setupHandlers]\n E --> F[MCP SDK]\n```\n\n资料来源：[CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n### Tool Naming Conventions\n\nTool names derive from the OpenAPI `operationId` field:\n\n| OpenAPI operationId | MCP Tool Name |\n|---------------------|---------------|\n| `query-data-source` | `query-data-source` |\n| `retrieve-a-data-source` | `retrieve-a-data-source` |\n| `update-a-data-source` | `update-a-data-source` |\n\nNames are truncated to 64 characters and converted to title case for display purposes.\n\n## OpenAPI Schema Conversion\n\nThe parser converts OpenAPI schemas to JSON Schema format for MCP tool definitions. The `convertOpenApiSchemaToJsonSchema` method handles complex type conversions:\n\n```typescript\n// Handles the following conversions:\n// - binary format → uri-reference format\n// - oneOf/anyOf/allOf → proper JSON Schema composition\n// - const values for discriminators\n// - default values preservation\n```\n\n资料来源：[src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n\n### Response Schema Handling\n\nThe `extractResponseType` method processes API responses:\n\n1. Looks for success responses (200, 201, 202, 204)\n2. Extracts JSON schema from `application/json` content type\n3. Preserves response descriptions\n4. Falls back to generic formats for non-JSON responses\n\n```typescript\nprivate extractResponseType(responses: OpenAPIV3.ResponsesObject | undefined): IJsonSchema | null\n```\n\n## HTTP Client Architecture\n\nThe HTTP client handles parameter serialization and request execution:\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Client\n participant Proxy as MCPProxy\n participant Client as HttpClient\n participant Notion as Notion API\n \n MCP->>Proxy: Call Tool\n Proxy->>Client: Execute with params\n Client->>Client: Deserialize JSON strings\n Client->>Notion: API Request\n Notion-->>Client: Response\n Client-->>Proxy: Formatted Result\n Proxy-->>MCP: Tool Response\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n\n### Parameter Deserialization\n\nThe `deserializeParams` function recursively processes incoming parameters to convert JSON-like strings into actual objects:\n\n```typescript\nfunction deserializeParams(params: Record): Record\n```\n\nThis handles:\n- JSON object strings → parsed objects\n- JSON array strings → parsed arrays\n- Nested object deserialization\n- Array item deserialization\n\n资料来源：[src/openapi-mcp-server/mcp/proxy.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts)\n\n## API Version Configuration\n\nThe server uses the Notion API version `2025-09-03` (Data Source Edition):\n\n```bash\n# Via environment variable\nNOTION_TOKEN=ntn_****\n\n# Or via OPENAPI_MCP_HEADERS\nOPENAPI_MCP_HEADERS='{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\"}'\n```\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Configuration Options\n\n### Transport Modes\n\n| Transport | Default | Description |\n|-----------|---------|-------------|\n| `stdio` | Yes | Standard I/O transport |\n| `http` | No | Streamable HTTP transport |\n\n### HTTP Transport Authentication\n\n```bash\n# Using command line\nnotion-mcp-server --transport http --port 3000 --auth-token your-token\n\n# Or via environment variable\nAUTH_TOKEN=your-token notion-mcp-server --transport http\n```\n\nThe `--auth-token` command line argument takes precedence over the `AUTH_TOKEN` environment variable.\n\n## Build and Deployment\n\n### Version Information\n\n| Property | Value |\n|----------|-------|\n| Package Name | `@notionhq/notion-mcp-server` |\n| Version | 2.3.0 |\n| License | MIT |\n\n### Build Commands\n\n```bash\nnpm run build # TypeScript compilation + CLI bundling\nnpm test # Run vitest tests\nnpm run dev # Start dev server with hot reload\n```\n\n### Docker Deployment\n\n```bash\n# Build locally\ndocker compose build\n\n# Run with NOTION_TOKEN\ndocker run --rm -i -e NOTION_TOKEN=ntn_**** notion-mcp-server\n```\n\n## Key Dependencies\n\n| Dependency | Version | Purpose |\n|------------|---------|---------|\n| `@modelcontextprotocol/sdk` | ^1.25.1 | MCP protocol implementation |\n| `axios` | ^1.8.4 | HTTP client |\n| `openapi-client-axios` | ^7.5.5 | OpenAPI client |\n| `zod` | 3.24.1 | Schema validation |\n\n## See Also\n\n- [Notion MCP Server Repository](https://github.com/makenotion/notion-mcp-server)\n- [MCP Protocol Specification](https://spec.modelcontextprotocol.io/)\n- [Notion API Documentation](https://developers.notion.com/reference/intro)\n\n---\n\n\n\n## Authentication System\n\n### 相关页面\n\n相关主题：[Transport Layers](#page-transport-layers), [npm Installation and Configuration](#page-npm-installation)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n- [src/openapi-mcp-server/client/http-client.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [src/openapi-mcp-server/openapi/parser.ts](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts)\n
\n\n# Authentication System\n\nThe Notion MCP Server implements a dual-layer authentication system that secures both the communication between MCP clients and the server, as well as the requests made to the Notion API.\n\n## Overview\n\nThe authentication system serves two distinct purposes:\n\n1. **Transport Authentication**: Secures client-to-server communication when using the Streamable HTTP transport\n2. **Notion API Authentication**: Authenticates requests to the Notion API using integration tokens\n\n```\n┌─────────────┐ Bearer Token Auth ┌──────────────────┐ Notion Token ┌─────────────┐\n│ MCP Client │ ◄──────────────────────────► │ MCP Server │ ◄───────────────────► │ Notion API │\n└─────────────┘ (HTTP Transport) └──────────────────┘ └─────────────┘\n```\n\n## Transport Authentication (HTTP)\n\nWhen running the server with `--transport http`, bearer token authentication is enforced to protect the MCP endpoint from unauthorized access.\n\n### Configuration Methods\n\n| Method | Priority | Description |\n|--------|----------|-------------|\n| `--auth-token` CLI flag | Highest | Passed directly via command line |\n| `AUTH_TOKEN` environment variable | Middle | Set in shell environment |\n| Auto-generated token | Fallback | Generated automatically if neither is provided |\n\n### Command Line Options\n\n```bash\n# Recommended: Custom token via command line\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n\n# Alternative: Token via environment variable\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq/notion-mcp-server --transport http\n\n# Development: Auto-generated token\nnpx @notionhq/notion-mcp-server --transport http\n\n# Disable authentication (NOT recommended for production)\nnpx @notionhq/notion-mcp-server --transport http --disable-auth\n```\n\n### Token Validation Flow\n\n```mermaid\ngraph TD\n A[HTTP Request to /mcp] --> B{Auth Disabled?}\n B -->|Yes| E[Process Request]\n B -->|No| C{Token Present?}\n C -->|No| F[Return 401 Unauthorized]\n C -->|Yes| G{Token Valid?}\n G -->|No| H[Return 403 Forbidden]\n G -->|Yes| E\n F --> I[Error: Missing bearer token]\n H --> J[Error: Invalid bearer token]\n```\n\n### Error Responses\n\nThe server returns standardized JSON-RPC error responses for authentication failures:\n\n**Missing Token (401)**\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"error\": {\n \"code\": -32001,\n \"message\": \"Unauthorized: Missing bearer token\"\n },\n \"id\": null\n}\n```\n\n**Invalid Token (403)**\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"error\": {\n \"code\": -32002,\n \"message\": \"Forbidden: Invalid bearer token\"\n },\n \"id\": null\n}\n```\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n### Health Endpoint Exception\n\nThe `/health` endpoint is accessible without authentication, allowing health checks without bearer token validation:\n\n```typescript\napp.get('/health', (req, res) => {\n res.status(200).json({\n status: 'healthy',\n timestamp: new Date().toISOString(),\n transport: 'http',\n port: options.port\n })\n})\n```\n\n资料来源：[scripts/start-server.ts:1-100](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Notion API Authentication\n\nThe server authenticates with the Notion API using integration tokens configured via environment variables.\n\n### Configuration Options\n\n| Environment Variable | Description | Recommended |\n|---------------------|-------------|-------------|\n| `NOTION_TOKEN` | Notion integration secret token (recommended) | ✅ |\n| `OPENAPI_MCP_HEADERS` | JSON string with custom headers including Authorization | Alternative |\n\n### Using NOTION_TOKEN (Recommended)\n\n```bash\nNOTION_TOKEN=ntn_**** npx @notionhq/notion-mcp-server\n```\n\n### Using OPENAPI_MCP_HEADERS (Advanced)\n\n```bash\nOPENAPI_MCP_HEADERS='{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\"}' \\\n npx @notionhq/notion-mcp-server\n```\n\n### Header Parsing\n\nThe server parses authentication headers from the environment variable:\n\n```typescript\nprivate parseHeadersFromEnv(): Record {\n const headers: Record = {}\n const headerConfig = process.env.OPENAPI_MCP_HEADERS\n if (headerConfig) {\n try {\n const parsed = JSON.parse(headerConfig)\n Object.assign(headers, parsed)\n } catch {\n // Invalid JSON, skip header parsing\n }\n }\n return headers\n}\n```\n\n资料来源：[src/openapi-mcp-server/client/http-client.ts:1-50](https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts)\n\n## Docker Deployment\n\n### Option 1: Using NOTION_TOKEN\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"NOTION_TOKEN\", \"notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### Option 2: Using OPENAPI_MCP_HEADERS\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"OPENAPI_MCP_HEADERS\", \"notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\":\\\"Bearer ntn_****\\\",\\\"Notion-Version\\\":\\\"2025-09-03\\\"}\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Client Configuration Examples\n\n### Cursor / Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### Zed\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\" }\"\n }\n },\n \"settings\": {}\n }\n }\n}\n```\n\n### GitHub Copilot CLI\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n## API Version Header\n\nThe server uses Notion API version `2025-09-03` (Data Source Edition) for all API requests:\n\n```typescript\nconst headers = {\n 'Authorization': `Bearer ${notionToken}`,\n 'Notion-Version': '2025-09-03'\n}\n```\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Making HTTP Requests\n\nAll requests to the Streamable HTTP transport must include the bearer token:\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n## Security Considerations\n\n| Concern | Mitigation |\n|---------|------------|\n| Token exposure in logs | Use `--auth-token` flag instead of environment variable when possible |\n| Plaintext token transmission | Always use HTTPS in production deployments |\n| Token rotation | Support multiple configuration methods for easy rotation |\n| Unauthorized access | Bearer token required by default for HTTP transport |\n\n## Integration Token Setup\n\nBefore using the server, ensure your Notion integration has been granted access to the target pages:\n\n1. Visit the target page in Notion\n2. Click on the three dots menu\n3. Select \"Connect to integration\"\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n---\n\n\n\n## npm Installation and Configuration\n\n### 相关页面\n\n相关主题：[Docker Deployment](#page-docker-deployment), [Quick Start Guide](#page-quickstart)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n- [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n- [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n- [scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n
\n\n# npm Installation and Configuration\n\nThe Notion MCP Server is a Model Context Protocol (MCP) server that exposes the Notion API as MCP tools. This page covers all aspects of installing and configuring the server using npm, including setup for various AI client applications, environment configuration, and local development workflows.\n\n## Overview\n\nThe server is distributed as an npm package (`@notionhq/notion-mcp-server`) and can be installed via `npx` for immediate use or added to projects for development. It supports two transport modes: `stdio` for local MCP clients and `http` for remote access with authentication.\n\n| Transport Mode | Use Case | Authentication |\n|----------------|----------|----------------|\n| `stdio` | Local MCP clients (Cursor, Claude Desktop) | Via `NOTION_TOKEN` env var |\n| `http` | Remote access, development servers | Bearer token (auto-generated or custom) |\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Prerequisites\n\nBefore installing the Notion MCP Server, ensure you have:\n\n- **Node.js** version compatible with the package requirements\n- **npm** or **npx** for package management\n- A **Notion integration token** from the [Notion Developer Portal](https://www.notion.so/my-integrations)\n\n### Obtaining Your Notion Integration Token\n\n1. Navigate to [Notion Developer Portal](https://www.notion.so/my-integrations)\n2. Create a new integration or select an existing one\n3. Copy the **Internal Integration Token** (format: `ntn_...`)\n4. Share the target Notion pages with your integration by opening the page and selecting **\"Connect to integration\"**\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Installation Methods\n\n### Using npx (Recommended for Immediate Use)\n\nThe simplest method to run the server without global installation:\n\n```bash\nnpx -y @notionhq/notion-mcp-server\n```\n\nFor stdio transport (default):\n\n```bash\nnpx -y @notionhq/notion-mcp-server --transport stdio\n```\n\nFor HTTP transport with auto-generated auth token:\n\n```bash\nnpx -y @notionhq/notion-mcp-server --transport http\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Local Development Installation\n\nFor testing changes or contributing to the project:\n\n```bash\n# Clone the repository\ngit clone https://github.com/makenotion/notion-mcp-server.git\ncd notion-mcp-server\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\nThe build script compiles TypeScript and bundles the CLI:\n\n```bash\nnpm run build # TypeScript compilation + CLI bundling\nnpm test # Run vitest tests\nnpm run dev # Start dev server with hot reload\n```\n\n资料来源：[CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md) and [package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n### Using npm link for Local Testing\n\nTo test local changes in AI clients without publishing:\n\n```bash\n# From repository root\nnpm link\n\n# The command creates a machine-global symlink\n# to the notion-mcp-server package\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Environment Configuration\n\n### Environment Variables\n\n| Variable | Description | Required | Priority |\n|----------|-------------|----------|----------|\n| `NOTION_TOKEN` | Notion integration token (`ntn_...`) | Yes (for stdio) | Recommended |\n| `OPENAPI_MCP_HEADERS` | JSON string with custom headers | Alternative to `NOTION_TOKEN` | Alternative |\n| `AUTH_TOKEN` | Bearer token for HTTP transport auth | No (for HTTP) | Lower than CLI arg |\n| `NODE_ENV` | Set to `test` for running tests | For testing | N/A |\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts) and [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Using NOTION_TOKEN (Recommended)\n\n```bash\nNOTION_TOKEN=\"ntn_your_integration_token\" npx -y @notionhq/notion-mcp-server\n```\n\n### Using OPENAPI_MCP_HEADERS (Advanced)\n\nFor custom headers including Notion-Version specification:\n\n```bash\nOPENAPI_MCP_HEADERS='{\"Authorization\": \"Bearer ntn_your_token\", \"Notion-Version\": \"2025-09-03\"}' \\\n npx -y @notionhq/notion-mcp-server\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## MCP Client Configuration\n\n### Cursor & Claude Desktop\n\nAdd configuration to your client's MCP settings file:\n\n**Cursor:** `~/.cursor/mcp.json` \n**Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n#### Option 1: Using NOTION_TOKEN (Recommended)\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_your_integration_token\"\n }\n }\n }\n}\n```\n\n#### Option 2: Using OPENAPI_MCP_HEADERS\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_your_token\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\"}\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Zed Editor\n\nAdd to `settings.json`:\n\n```json\n{\n \"context_servers\": {\n \"some-context-server\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_your_token\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\"}\"\n }\n },\n \"settings\": {}\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### GitHub Copilot CLI\n\nUse interactive addition:\n\n```bash\n/mcp add\n```\n\nOr manually edit `~/.copilot/mcp-config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@notionhq/notion-mcp-server\"],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_your_integration_token\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Testing Local Changes in Cursor\n\nFor testing local development changes:\n\n1. Run `npm link` from the repository root\n2. Merge this configuration into `~/.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"notion-local-package\": {\n \"command\": \"notion-mcp-server\",\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_your_integration_token\"\n }\n }\n }\n}\n```\n\n3. After testing, run `npm unlink` to cleanup\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## HTTP Transport Configuration\n\n### Command Line Options\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http [options]\n```\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--transport ` | Transport type: `stdio` or `http` | `stdio` |\n| `--port ` | Port for HTTP server | `3000` |\n| `--auth-token ` | Bearer token for authentication | Auto-generated |\n| `--disable-auth` | Disable bearer token authentication | `false` |\n| `--help`, `-h` | Show help message | N/A |\n\nThe `--auth-token` argument takes precedence over the `AUTH_TOKEN` environment variable.\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts) and [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Authentication Options for HTTP Transport\n\n#### Option 1: Auto-generated Token (Development Only)\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http\n```\n\nThe server displays the generated token:\n\n```\nGenerated auth token: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\nUse this token in the Authorization header: Bearer a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\n```\n\n#### Option 2: Custom Token via CLI (Recommended for Production)\n\n```bash\nnpx @notionhq/notion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\n#### Option 3: Custom Token via Environment Variable\n\n```bash\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq/notion-mcp-server --transport http\n```\n\n### Making HTTP Requests\n\nAll requests require the bearer token in the Authorization header:\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Docker Installation\n\n### Option 1: Using Official Docker Hub Image\n\n#### With NOTION_TOKEN\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\", \"NOTION_TOKEN\",\n \"mcp/notion\"\n ],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_your_integration_token\"\n }\n }\n }\n}\n```\n\n#### With OPENAPI_MCP_HEADERS\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\", \"OPENAPI_MCP_HEADERS\",\n \"mcp/notion\"\n ],\n \"env\": {\n \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\":\\\"Bearer ntn_your_token\\\",\\\"Notion-Version\\\":\\\"2025-09-03\\\"}\"\n }\n }\n }\n}\n```\n\n### Option 2: Building Locally\n\n```bash\n# Build the Docker image\ndocker compose build\n\n# Run with local image\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN=ntn_your_token\",\n \"notion-mcp-server\"\n ]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Available Scripts\n\n| Script | Description |\n|--------|-------------|\n| `npm run build` | Compiles TypeScript and bundles the CLI |\n| `npm run dev` | Starts dev server with hot reload using tsx |\n| `npm test` | Runs vitest tests |\n| `npm run test:watch` | Runs tests in watch mode |\n| `npm run test:coverage` | Runs tests with coverage report |\n\n资料来源：[package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json) and [CLAUDE.md](https://github.com/makenotion/notion-mcp-server/blob/main/CLAUDE.md)\n\n## Package Metadata\n\n| Property | Value |\n|----------|-------|\n| Package Name | `@notionhq/notion-mcp-server` |\n| Version | 2.3.0 |\n| License | MIT |\n| CLI Entry | `bin/cli.mjs` |\n| Main Entry | `index.js` |\n| Type | ES Module |\n\n资料来源：[package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json)\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Token not recognized | Ensure `NOTION_TOKEN` or `OPENAPI_MCP_HEADERS` is set in environment |\n| JSON parsing errors | Check that `OPENAPI_MCP_HEADERS` is properly escaped JSON |\n| Client can't connect | Verify integration has access to the target Notion pages |\n| Local changes not reflected | Run `npm unlink` then `npm link` again |\n\n### Verifying Installation\n\nTest the server can start:\n\n```bash\nnpx -y @notionhq/notion-mcp-server --help\n```\n\nExpected output shows available options including `--transport`, `--port`, `--auth-token`, and `--help`.\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n---\n\n\n\n## Docker Deployment\n\n### 相关页面\n\n相关主题：[npm Installation and Configuration](#page-npm-installation), [Transport Layers](#page-transport-layers)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [Dockerfile](https://github.com/makenotion/notion-mcp-server/blob/main/Dockerfile)\n- [docker-compose.yml](https://github.com/makenotion/notion-mcp-server/blob/main/docker-compose.yml)\n- [.dockerignore](https://github.com/makenotion/notion-mcp-server/blob/main/.dockerignore)\n
\n\n# Docker Deployment\n\nThe notion-mcp-server provides official Docker container support for running the MCP server in a containerized environment. This deployment option is ideal for users who prefer not to install Node.js dependencies locally or want to ensure consistent runtime environments across different systems.\n\n## Overview\n\nThe Docker deployment for notion-mcp-server offers two primary approaches for containerization:\n\n| Approach | Description | Use Case |\n|---------|-------------|----------|\n| **Official Image** | Use pre-built image from Docker Hub (`mcp/notion`) | Quick setup, no build required |\n| **Local Build** | Build image locally using `docker compose` | Development, customization |\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Client App
Cursor/Claude/Zed] --> B[MCP Client Config]\n B --> C[Docker Container
notion-mcp-server]\n C --> D[Notion API
api.notion.com]\n \n E[Environment Variables] --> C\n E --> F[NOTION_TOKEN]\n E --> G[OPENAPI_MCP_HEADERS]\n E --> H[AUTH_TOKEN
HTTP transport only]\n```\n\n## Environment Configuration\n\n### Required Variables\n\n| Variable | Description | Required | Example |\n|----------|-------------|----------|---------|\n| `NOTION_TOKEN` | Notion integration secret | Yes (recommended) | `ntn_****` |\n| `OPENAPI_MCP_HEADERS` | JSON string with custom headers | No (alternative) | `{\"Authorization\": \"Bearer ntn_****\"}` |\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Authentication Token (HTTP Transport)\n\nWhen using the HTTP transport mode, an additional bearer token is required:\n\n| Variable | CLI Argument | Priority |\n|----------|-------------|----------|\n| `AUTH_TOKEN` | `--auth-token` | Lower |\n| Environment variable | `--auth-token` argument | Higher (overrides env var) |\n\n资料来源：[scripts/start-server.ts](https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts)\n\n## Deployment Options\n\n### Option 1: Using Official Docker Hub Image\n\nThe official image is available at `mcp/notion` on Docker Hub.\n\n#### STDIO Transport Configuration\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN\",\n \"mcp/notion\"\n ],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n#### HTTP Transport Configuration\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN\",\n \"mcp/notion\",\n \"--transport\",\n \"http\",\n \"--port\",\n \"3000\",\n \"--auth-token\",\n \"your-secret-token\"\n ],\n \"env\": {\n \"NOTION_TOKEN\": \"ntn_****\"\n }\n }\n }\n}\n```\n\n### Option 2: Building Locally with Docker Compose\n\n#### Build Process\n\n```bash\n# Build the Docker image\ndocker compose build\n```\n\n#### Configuration for Local Build\n\nReplace `mcp/notion` with `notion-mcp-server` in your MCP client configuration:\n\n```json\n{\n \"mcpServers\": {\n \"notionApi\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"NOTION_TOKEN=ntn_****\",\n \"notion-mcp-server\"\n ]\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## HTTP Transport with Docker\n\nWhen running with Docker, the HTTP transport requires special handling for headers and authentication.\n\n### Authentication Modes\n\n```mermaid\ngraph LR\n A[Docker Container] --> B{Transport Mode}\n B -->|stdio| C[No Auth Required]\n B -->|http| D[Bearer Token Required]\n \n E[Request] --> F[Authorization Header]\n F --> D\n D --> G{Token Valid?}\n G -->|Yes| H[Process Request]\n G -->|No| I[401 Unauthorized]\n```\n\n### Request Format\n\n```bash\ncurl -H \"Authorization: Bearer your-token-here\" \\\n -H \"Content-Type: application/json\" \\\n -H \"mcp-session-id: your-session-id\" \\\n -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n http://localhost:3000/mcp\n```\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Integration Setup\n\n### Notion Workspace Configuration\n\nBefore using the Docker container, ensure your integration has access to target pages:\n\n1. Visit the target Notion page\n2. Click on the **three dots menu** (⋮)\n3. Select **\"Connect to integration\"**\n\n资料来源：[README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n### Client-Specific Configuration\n\n| Client | Configuration File | Example |\n|--------|-------------------|---------|\n| Cursor | `.cursor/mcp.json` | [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md) |\n| Claude Desktop | `claude_desktop_config.json` | `~/Library/Application Support/Claude/` |\n| Zed | `settings.json` | `context_servers` section |\n| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | Interactive `/mcp add` or manual edit |\n\n## Environment Variable Priority\n\n```mermaid\ngraph TD\n A[Runtime] --> B{Environment Check}\n B --> C[NOTION_TOKEN Set?]\n B --> D[OPENAPI_MCP_HEADERS Set?]\n \n C -->|Yes| E[Use NOTION_TOKEN]\n C -->|No| F[Use OPENAPI_MCP_HEADERS]\n \n D -->|Yes| G[Use Custom Headers]\n D -->|No| H[Error: Missing Token]\n```\n\n| Priority | Variable | Notes |\n|----------|----------|-------|\n| 1 | `NOTION_TOKEN` | Recommended for most use cases |\n| 2 | `OPENAPI_MCP_HEADERS` | For advanced header customization |\n\n## Build Commands Reference\n\n| Command | Description |\n|---------|-------------|\n| `npm run build` | TypeScript compilation + CLI bundling |\n| `docker compose build` | Build Docker image locally |\n| `npm test` | Run vitest tests |\n\n资料来源：[package.json](https://github.com/makenotion/notion-mcp-server/blob/main/package.json), [README.md](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)\n\n## Security Considerations\n\n### Token Handling\n\n- **Never commit tokens** to version control\n- Use environment variables or secret management tools\n- Rotate tokens periodically through Notion developer portal\n\n### Network Security\n\n- The HTTP transport binds to `http://0.0.0.0:/mcp`\n- Always use authentication tokens for HTTP transport in production\n- Consider network isolation based on your deployment environment\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| Container exits immediately | Verify `NOTION_TOKEN` is valid and set correctly |\n| Authentication failures | Check bearer token matches `--auth-token` argument |\n| Port conflicts | Change port using `--port` argument |\n| Permission denied | Ensure Docker daemon is running and user has Docker permissions |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：makenotion/notion-mcp-server\n\n摘要：发现 21 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：配置坑 - 来源证据：BUG: Tool `query_data_sources` not available。\n\n## 1. 配置坑 · 来源证据：BUG: Tool `query_data_sources` not available\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：BUG: Tool `query_data_sources` not available\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eef5bea2e30f4ef6b0ebbec184ad57bc | https://github.com/makenotion/notion-mcp-server/issues/256 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e292459f0a6b4c38ab30d85d1fed7988 | https://github.com/makenotion/notion-mcp-server/issues/232 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missing POST /v1/databases tool\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_00471efb0dd04e9a998d767773687158 | https://github.com/makenotion/notion-mcp-server/issues/218 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c42a4b966290466e9d4c8678f1530d70 | https://github.com/makenotion/notion-mcp-server/issues/269 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：Notion MCP server does not work with Claude Code\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Notion MCP server does not work with Claude Code\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f225074bf40440978c5542d0a0553a33 | https://github.com/makenotion/notion-mcp-server/issues/277 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 6. 安全/权限坑 · 来源证据：OAuth token expires too frequently — requires re-authentication 3+ times per week\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token expires too frequently — requires re-authentication 3+ times per week\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6e81d503097248cb8099528ad547bc67 | https://github.com/makenotion/notion-mcp-server/issues/225 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Feature Request: Property-based filtering in notion-search for database queries\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Property-based filtering in notion-search for database queries\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b9e32ab88c7e48818bc99b84652be1ab | https://github.com/makenotion/notion-mcp-server/issues/278 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：Ontheia listed as compatible client — works great with notion-mcp-server\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ontheia listed as compatible client — works great with notion-mcp-server\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3fc1b045a8d44d0fb100ada453a88281 | https://github.com/makenotion/notion-mcp-server/issues/287 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cf7210b63f984b539554678f387c7e82 | https://github.com/makenotion/notion-mcp-server/issues/283 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 配置坑 · 来源证据：Enhancement: Expand blockObjectRequest to support all Notion block types\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Expand blockObjectRequest to support all Notion block types\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1dca271be3594278a2b6cae74a5a3caf | https://github.com/makenotion/notion-mcp-server/issues/282 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 配置坑 · 来源证据：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6ed1925ce08546dabe29e4f24e8a5967 | https://github.com/makenotion/notion-mcp-server/issues/281 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：Schema quality: 8 required parameters missing descriptions\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Schema quality: 8 required parameters missing descriptions\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3874c96ff07545e58a89907777de0799 | https://github.com/makenotion/notion-mcp-server/issues/280 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 维护坑 · 来源证据：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_201ffa8849a546d7aa12e1ea13455afb | https://github.com/makenotion/notion-mcp-server/issues/286 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | last_activity_observed missing\n\n## 16. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 来源证据：v2.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6bd57dcedd924ba5a565340c6538b43c | https://github.com/makenotion/notion-mcp-server/releases/tag/v2.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR me…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR merge)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_805c993b34ef42b88c0832132f5794fc | https://github.com/makenotion/notion-mcp-server/issues/284 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：makenotion/notion-mcp-server\n\n摘要：发现 21 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：配置坑 - 来源证据：BUG: Tool `query_data_sources` not available。\n\n## 1. 配置坑 · 来源证据：BUG: Tool `query_data_sources` not available\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：BUG: Tool `query_data_sources` not available\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eef5bea2e30f4ef6b0ebbec184ad57bc | https://github.com/makenotion/notion-mcp-server/issues/256 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug Report: Notion MCP — Status Property \"in_progress\" Group Options Not Recognized via API\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e292459f0a6b4c38ab30d85d1fed7988 | https://github.com/makenotion/notion-mcp-server/issues/232 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missi…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：API-create-a-data-source and API-update-a-data-source return invalid_request_url — database creation unreliable + missing POST /v1/databases tool\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_00471efb0dd04e9a998d767773687158 | https://github.com/makenotion/notion-mcp-server/issues/218 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安全/权限坑 · 来源证据：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Internal Server Error on OAuth callback when connecting via Claude.ai (Hosted MCP)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c42a4b966290466e9d4c8678f1530d70 | https://github.com/makenotion/notion-mcp-server/issues/269 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 安全/权限坑 · 来源证据：Notion MCP server does not work with Claude Code\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Notion MCP server does not work with Claude Code\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f225074bf40440978c5542d0a0553a33 | https://github.com/makenotion/notion-mcp-server/issues/277 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 6. 安全/权限坑 · 来源证据：OAuth token expires too frequently — requires re-authentication 3+ times per week\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token expires too frequently — requires re-authentication 3+ times per week\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6e81d503097248cb8099528ad547bc67 | https://github.com/makenotion/notion-mcp-server/issues/225 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Feature Request: Property-based filtering in notion-search for database queries\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Property-based filtering in notion-search for database queries\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b9e32ab88c7e48818bc99b84652be1ab | https://github.com/makenotion/notion-mcp-server/issues/278 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：Ontheia listed as compatible client — works great with notion-mcp-server\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ontheia listed as compatible client — works great with notion-mcp-server\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3fc1b045a8d44d0fb100ada453a88281 | https://github.com/makenotion/notion-mcp-server/issues/287 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: notion-create-view silently drops FILTER on Status property (no error, no warning)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_cf7210b63f984b539554678f387c7e82 | https://github.com/makenotion/notion-mcp-server/issues/283 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 配置坑 · 来源证据：Enhancement: Expand blockObjectRequest to support all Notion block types\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Enhancement: Expand blockObjectRequest to support all Notion block types\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1dca271be3594278a2b6cae74a5a3caf | https://github.com/makenotion/notion-mcp-server/issues/282 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 配置坑 · 来源证据：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] FILTER directive in view DSL silently drops filters for Relation and Rollup properties\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6ed1925ce08546dabe29e4f24e8a5967 | https://github.com/makenotion/notion-mcp-server/issues/281 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：Schema quality: 8 required parameters missing descriptions\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Schema quality: 8 required parameters missing descriptions\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3874c96ff07545e58a89907777de0799 | https://github.com/makenotion/notion-mcp-server/issues/280 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 维护坑 · 来源证据：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：synced_block_reference: URL inside url= attribute gets auto-converted to , mangling the tag\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_201ffa8849a546d7aa12e1ea13455afb | https://github.com/makenotion/notion-mcp-server/issues/286 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | last_activity_observed missing\n\n## 16. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 来源证据：v2.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6bd57dcedd924ba5a565340c6538b43c | https://github.com/makenotion/notion-mcp-server/releases/tag/v2.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR me…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.2.1 ships stale bin/cli.mjs — PR #212 double-serialization fix not included in bundle (published 33 min before PR merge)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_805c993b34ef42b88c0832132f5794fc | https://github.com/makenotion/notion-mcp-server/issues/284 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# notion-mcp-server - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for makenotion/notion-mcp-server.\n\nProject:\n- Name: notion-mcp-server\n- Repository: https://github.com/makenotion/notion-mcp-server\n- Summary: Official Notion MCP Server\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Official Notion MCP Server\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Official Notion MCP Server\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-introduction: Introduction to Notion MCP Server. Produce one small intermediate artifact and wait for confirmation.\n2. page-quickstart: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. page-transport-layers: Transport Layers. Produce one small intermediate artifact and wait for confirmation.\n5. page-available-tools: Available MCP Tools. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/makenotion/notion-mcp-server\n- https://github.com/makenotion/notion-mcp-server#readme\n- README.md\n- package.json\n- CLAUDE.md\n- src/init-server.ts\n- src/openapi-mcp-server/index.ts\n- src/openapi-mcp-server/client/http-client.ts\n- src/openapi-mcp-server/openapi/parser.ts\n- src/openapi-mcp-server/auth/index.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：makenotion/notion-mcp-server\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx @notionhq/notion-mcp-server\n```\n\n来源：https://github.com/makenotion/notion-mcp-server#readme\n\n## 来源\n\n- repo: https://github.com/makenotion/notion-mcp-server\n- docs: https://github.com/makenotion/notion-mcp-server#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_8ca90274aa7b4b399787d5d55144dc3a" }