[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-makenotion--notion-mcp-server":3,"tool-makenotion--notion-mcp-server":64},[4,17,27,35,48,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",140436,2,"2026-04-05T23:32:43",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,43,44,45,15,46,26,13,47],"数据工具","视频","插件","其他","音频",{"id":49,"name":50,"github_repo":51,"description_zh":52,"stars":53,"difficulty_score":10,"last_commit_at":54,"category_tags":55,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,46],{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},2181,"OpenHands","OpenHands\u002FOpenHands","OpenHands 是一个专注于 AI 驱动开发的开源平台，旨在让智能体（Agent）像人类开发者一样理解、编写和调试代码。它解决了传统编程中重复性劳动多、环境配置复杂以及人机协作效率低等痛点，通过自动化流程显著提升开发速度。\n\n无论是希望提升编码效率的软件工程师、探索智能体技术的研究人员，还是需要快速原型验证的技术团队，都能从中受益。OpenHands 提供了灵活多样的使用方式：既可以通过命令行（CLI）或本地图形界面在个人电脑上轻松上手，体验类似 Devin 的流畅交互；也能利用其强大的 Python SDK 自定义智能体逻辑，甚至在云端大规模部署上千个智能体并行工作。\n\n其核心技术亮点在于模块化的软件智能体 SDK，这不仅构成了平台的引擎，还支持高度可组合的开发模式。此外，OpenHands 在 SWE-bench 基准测试中取得了 77.6% 的优异成绩，证明了其解决真实世界软件工程问题的能力。平台还具备完善的企业级功能，支持与 Slack、Jira 等工具集成，并提供细粒度的权限管理，适合从个人开发者到大型企业的各类用户场景。",70626,"2026-04-05T22:51:36",[26,15,13,45],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":69,"readme_en":70,"readme_zh":71,"quickstart_zh":72,"use_case_zh":73,"hero_image_url":74,"owner_login":75,"owner_name":76,"owner_avatar_url":77,"owner_bio":78,"owner_company":79,"owner_location":79,"owner_email":80,"owner_twitter":81,"owner_website":82,"owner_url":83,"languages":84,"stars":97,"forks":98,"last_commit_at":99,"license":100,"difficulty_score":23,"env_os":101,"env_gpu":102,"env_ram":103,"env_deps":104,"category_tags":111,"github_topics":79,"view_count":23,"oss_zip_url":79,"oss_zip_packed_at":79,"status":16,"created_at":112,"updated_at":113,"faqs":114,"releases":145},2602,"makenotion\u002Fnotion-mcp-server","notion-mcp-server","Official Notion MCP Server","notion-mcp-server 是 Notion 官方推出的模型上下文协议（MCP）服务器，旨在让 AI 助手能够安全、高效地读取和操作你的 Notion 工作区内容。它解决了传统 API 集成中配置繁琐（如需手动处理 JSON 和令牌）的痛点，通过标准 OAuth 实现简易安装，并提供了专为 AI 代理优化的工具集，例如支持以 Markdown 格式编辑页面，从而显著降低 Token 消耗。\n\n该项目特别适合开发者、AI 研究人员以及希望将大语言模型深度融入个人知识库管理的进阶用户。借助它，你可以构建能自动查询数据库、整理笔记或更新任务的智能体。其核心技术亮点在于紧跟 Notion API 演进，最新版本已全面适配“数据源（Data Source）”抽象概念，将原有的数据库操作工具升级为更通用的数据源管理工具，同时保持工具自动发现机制，无需修改代码即可平滑升级。需要注意的是，官方目前优先支持远程版 Notion MCP，本地版仓库未来可能停止维护，建议新用户直接关注远程部署方案以获得持续支持。","# Notion MCP Server\n\n> [!NOTE]\n>\n> We’ve introduced **Notion MCP**, a remote MCP server with the following improvements:\n>\n> - Easy installation via standard OAuth. No need to fiddle with JSON or API tokens anymore.\n> - Powerful tools tailored to AI agents, including editing pages in Markdown. These tools are designed with optimized token consumption in mind.\n>\n> Learn more and get started at [Notion MCP documentation](https:\u002F\u002Fdevelopers.notion.com\u002Fdocs\u002Fmcp).\n>\n> We are prioritizing, and only providing active support for, **Notion MCP** (remote). As a result:\n>\n> - We may sunset this local MCP server repository in the future.\n> - Issues and pull requests here are not actively monitored.\n> - Please do not file issues relating to the remote MCP here; instead, contact Notion support.\n\n![notion-mcp-sm](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_1efda450a8e2.png)\n\nThis project implements an [MCP server](https:\u002F\u002Fspec.modelcontextprotocol.io\u002F) for the [Notion API](https:\u002F\u002Fdevelopers.notion.com\u002Freference\u002Fintro).\n\n![mcp-demo](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_bf4dd2251501.png)\n\n---\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.\n\n### What changed\n\n**Removed tools (3):**\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 (7):**\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- All database operations now use `data_source_id` instead of `database_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 (for data sources)\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 tool names and parameters. The old database tools are no longer available.\n\nIf you have hardcoded tool names or prompts that reference the old database tools, update them to use the new data source tools:\n\n| Old Tool (v1.x) | New Tool (v2.0) | Parameter Change |\n| -------------- | --------------- | ---------------- |\n| `post-database-query` | `query-data-source` | `database_id` → `data_source_id` |\n| `update-a-database` | `update-a-data-source` | `database_id` → `data_source_id` |\n| `create-a-database` | `create-a-data-source` | No change (uses `parent.page_id`) |\n\n> **Note:** `retrieve-a-database` is still available and returns database metadata including the list of data source IDs. Use `retrieve-a-data-source` to get the schema and properties of a specific data source.\n\n**Total tools now: 22** (was 19 in v1.x)\n\n---\n\n### Installation\n\n#### 1. Setting up integration in Notion\n\nGo to [https:\u002F\u002Fwww.notion.so\u002Fprofile\u002Fintegrations](https:\u002F\u002Fwww.notion.so\u002Fprofile\u002Fintegrations) and create a new **internal** integration or select an existing one.\n\n![Creating a Notion Integration token](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_0346fcd3f0f7.png)\n\nWhile we limit the scope of Notion API's exposed (for example, you will not be able to delete databases via MCP), there is a non-zero risk to workspace data by exposing it to LLMs. Security-conscious users may want to further configure the Integration's _Capabilities_.\n\nFor example, you can create a read-only integration token by giving only \"Read content\" access from the \"Configuration\" tab:\n\n![Notion Integration Token Capabilities showing Read content checked](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_f40506137dd0.png)\n\n#### 2. Connecting content to integration\n\nEnsure relevant pages and databases are connected to your integration.\n\nTo do this, visit the **Access** tab in your internal integration settings. Edit access and select the pages you'd like to use.\n\n![Integration Access tab](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_dc602f009cee.png)\n\n![Edit integration access](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_90615fc52a97.png)\n\nAlternatively, you can grant page access individually. You'll need to visit the target page, and click on the 3 dots, and select \"Connect to integration\".\n\n![Adding Integration Token to Notion Connections](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_2efae4a4fe76.png)\n\n#### 3. Adding MCP config to your client\n\n##### Using npm\n\n###### Cursor & Claude\n\nAdd the following to your `.cursor\u002Fmcp.json` or `claude_desktop_config.json` (MacOS: `~\u002FLibrary\u002FApplication\\ Support\u002FClaude\u002Fclaude_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\u002Fnotion-mcp-server\"],\n      \"env\": {\n        \"NOTION_TOKEN\": \"ntn_****\"\n      }\n    }\n  }\n}\n```\n\n###### Option 2: Using OPENAPI_MCP_HEADERS (for advanced use cases)\n\n```json\n{\n  \"mcpServers\": {\n    \"notionApi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@notionhq\u002Fnotion-mcp-server\"],\n      \"env\": {\n        \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\" }\"\n      }\n    }\n  }\n}\n```\n\n###### Zed\n\nAdd the following to your `settings.json`\n\n```json\n{\n  \"context_servers\": {\n    \"some-context-server\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"-y\", \"@notionhq\u002Fnotion-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\nUse the Copilot CLI to interactively add the MCP server:\n\n```bash\n\u002Fmcp add\n```\n\nAlternatively, create or edit the configuration file `~\u002F.copilot\u002Fmcp-config.json` and add:\n\n```json\n{\n  \"mcpServers\": {\n    \"notionApi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@notionhq\u002Fnotion-mcp-server\"],\n      \"env\": {\n        \"NOTION_TOKEN\": \"ntn_****\"\n      }\n    }\n  }\n}\n```\n\nFor more information, see the [Copilot CLI documentation](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Fconcepts\u002Fagents\u002Fabout-copilot-cli).\n\n##### Using Docker\n\nThere are two options for running the MCP server with Docker:\n\n###### Option 1: Using the official Docker Hub image\n\nAdd the following to your `.cursor\u002Fmcp.json` or `claude_desktop_config.json`\n\nUsing NOTION_TOKEN (recommended):\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\u002Fnotion\"\n      ],\n      \"env\": {\n        \"NOTION_TOKEN\": \"ntn_****\"\n      }\n    }\n  }\n}\n```\n\nUsing OPENAPI_MCP_HEADERS (for advanced use cases):\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\u002Fnotion\"\n      ],\n      \"env\": {\n        \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\":\\\"Bearer ntn_****\\\",\\\"Notion-Version\\\":\\\"2025-09-03\\\"}\"\n      }\n    }\n  }\n}\n```\n\nThis approach:\n\n- Uses the official Docker Hub image\n- Properly handles JSON escaping via environment variables\n- Provides a more reliable configuration method\n\n###### Option 2: Building the Docker image locally\n\nYou can also build and run the Docker image locally. First, build the Docker image:\n\n```bash\ndocker compose build\n```\n\nThen, add the following to your `.cursor\u002Fmcp.json` or `claude_desktop_config.json`\n\nUsing NOTION_TOKEN (recommended):\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\nUsing OPENAPI_MCP_HEADERS (for advanced use cases):\n\n```json\n{\n  \"mcpServers\": {\n    \"notionApi\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--rm\",\n        \"-i\",\n        \"-e\",\n        \"OPENAPI_MCP_HEADERS={\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\"}\",\n        \"notion-mcp-server\"\n      ]\n    }\n  }\n}\n```\n\nDon't forget to replace `ntn_****` with your integration secret. Find it from your integration configuration tab:\n\n![Copying your Integration token from the Configuration tab in the developer portal](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_c2e68bd90ee0.png)\n\n### Transport options\n\nThe Notion MCP Server supports two transport modes:\n\n#### STDIO transport (default)\n\nThe default transport mode uses standard input\u002Foutput for communication. This is the standard MCP transport used by most clients like Claude Desktop.\n\n```bash\n# Run with default stdio transport\nnpx @notionhq\u002Fnotion-mcp-server\n\n# Or explicitly specify stdio\nnpx @notionhq\u002Fnotion-mcp-server --transport stdio\n```\n\n#### Streamable HTTP transport\n\nFor web-based applications or clients that prefer HTTP communication, you can use the Streamable HTTP transport:\n\n```bash\n# Run with Streamable HTTP transport on port 3000 (default)\nnpx @notionhq\u002Fnotion-mcp-server --transport http\n\n# Run on a custom port\nnpx @notionhq\u002Fnotion-mcp-server --transport http --port 8080\n\n# Run with a custom authentication token\nnpx @notionhq\u002Fnotion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\nWhen using Streamable HTTP transport, the server will be available at `http:\u002F\u002F0.0.0.0:\u003Cport>\u002Fmcp`.\n\n##### Authentication\n\nThe Streamable HTTP transport requires bearer token authentication for security. You have three options:\n\n###### Option 1: Auto-generated token (only for development)\n\n```bash\nnpx @notionhq\u002Fnotion-mcp-server --transport http\n```\n\nThe server will generate a secure random token and display it in the console:\n\n```text\nGenerated auth token: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\nUse this token in the Authorization header: Bearer a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\n```\n\n###### Option 2: Custom token via command line (recommended for production)\n\n```bash\nnpx @notionhq\u002Fnotion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\n###### Option 3: Custom token via environment variable (recommended for production)\n\n```bash\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq\u002Fnotion-mcp-server --transport http\n```\n\nThe command line argument `--auth-token` takes precedence over the `AUTH_TOKEN` environment variable if both are provided.\n\n##### Making HTTP requests\n\nAll requests to the Streamable HTTP transport must include the bearer token in the Authorization header:\n\n```bash\n# Example request\ncurl -H \"Authorization: Bearer your-token-here\" \\\n     -H \"Content-Type: application\u002Fjson\" \\\n     -H \"mcp-session-id: your-session-id\" \\\n     -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n     http:\u002F\u002Flocalhost:3000\u002Fmcp\n```\n\n**Note:** Make sure to set either the `NOTION_TOKEN` environment variable (recommended) or the `OPENAPI_MCP_HEADERS` environment variable with your Notion integration token when using either transport mode.\n\n### Examples\n\n1. Using the following instruction\n\n```text\nComment \"Hello MCP\" on page \"Getting started\"\n```\n\n   AI will correctly plan two API calls, `v1\u002Fsearch` and `v1\u002Fcomments`, to achieve the task\n\n1. Similarly, the following instruction will result in a new page named \"Notion MCP\" added to parent page \"Development\"\n\n```text\nAdd a page titled \"Notion MCP\" to page \"Development\"\n```\n\n1. You may also reference content ID directly\n\n```text\nGet the content of page 1a6b35e6e67f802fa7e1d27686f017f2\n```\n\n### Development\n\n#### Build & test\n\n```bash\nnpm run build\nnpm test\n```\n\n#### Execute\n\n```bash\nnpx -y --prefix \u002Fpath\u002Fto\u002Flocal\u002Fnotion-mcp-server @notionhq\u002Fnotion-mcp-server\n```\n\nTesting changes locally in Cursor:\n\n1. Run `npm link` command from repository root to create a machine-global symlink to the `notion-mcp-server` package.\n2. Merge the configuration snippet below into Cursor's `mcp.json` (or other MCP client you want to test with).\n3. (Cleanup) run `npm unlink` from repository root.\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#### Publish\n\n```bash\nnpm login\nnpm publish --access public\n```\n","# Notion MCP 服务器\n\n> [!NOTE]\n>\n> 我们推出了 **Notion MCP**，这是一个远程 MCP 服务器，具有以下改进：\n>\n> - 通过标准 OAuth 即可轻松安装。无需再手动处理 JSON 或 API 令牌。\n> - 强大的工具专为 AI 代理设计，包括以 Markdown 编辑页面的功能。这些工具在设计时充分考虑了优化的 token 消耗。\n>\n> 了解更多信息并开始使用，请访问 [Notion MCP 文档](https:\u002F\u002Fdevelopers.notion.com\u002Fdocs\u002Fmcp)。\n>\n> 我们目前优先支持且仅对 **Notion MCP**（远程）提供主动支持。因此：\n>\n> - 我们可能会在未来逐步停止维护此本地 MCP 服务器仓库。\n> - 此处的问题和拉取请求将不再被积极监控。\n> - 请勿在此处提交与远程 MCP 相关的问题；请改向 Notion 支持团队联系。\n\n![notion-mcp-sm](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_1efda450a8e2.png)\n\n本项目实现了用于 [Notion API](https:\u002F\u002Fdevelopers.notion.com\u002Freference\u002Fintro) 的 [MCP 服务器](https:\u002F\u002Fspec.modelcontextprotocol.io\u002F)。\n\n![mcp-demo](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_bf4dd2251501.png)\n\n---\n\n## ⚠️ 版本 2.0.0 的重大变更\n\n**版本 2.0.0 已迁移到 Notion API 2025-09-03**，该版本引入了数据源作为数据库的主要抽象概念。\n\n### 变更内容\n\n**移除的工具（3 个）：**\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**新增的工具（7 个）：**\n\n- `query-data-source` - 使用过滤器和排序查询数据源（数据库）\n- `retrieve-a-data-source` - 获取数据源的元数据和模式\n- `update-a-data-source` - 更新数据源属性\n- `create-a-data-source` - 创建新的数据源\n- `list-data-source-templates` - 列出数据源中的可用模板\n- `move-page` - 将页面移动到不同的父位置\n- `retrieve-a-database` - 获取数据库元数据，包括其数据源 ID\n\n**参数变更：**\n\n- 所有数据库操作现在使用 `data_source_id` 而不是 `database_id`\n- 搜索过滤器的值从 `[\"page\", \"database\"]` 更改为 `[\"page\", \"data_source\"]`\n- 页面创建现在同时支持 `page_id` 和 `database_id` 作为父级（适用于数据源）。\n\n### 我需要迁移吗？\n\n**无需更改代码。** MCP 工具会在服务器启动时自动发现。升级到 v2.0.0 后，AI 客户端会自动识别新的工具名称和参数。旧的数据库工具将不再可用。\n\n如果您硬编码了工具名称或提示中引用了旧的数据库工具，请将其更新为使用新的数据源工具：\n\n| 旧工具 (v1.x) | 新工具 (v2.0) | 参数变更 |\n| -------------- | --------------- | ---------------- |\n| `post-database-query` | `query-data-source` | `database_id` → `data_source_id` |\n| `update-a-database` | `update-a-data-source` | `database_id` → `data_source_id` |\n| `create-a-database` | `create-a-data-source` | 无变化（使用 `parent.page_id`） |\n\n> **注意：** `retrieve-a-database` 仍然可用，它会返回包含数据源 ID 列表的数据库元数据。如需获取特定数据源的模式和属性，请使用 `retrieve-a-data-source`。\n\n**当前总工具数：22 个**（v1.x 为 19 个）\n\n---\n\n### 安装\n\n#### 1. 在 Notion 中设置集成\n\n前往 [https:\u002F\u002Fwww.notion.so\u002Fprofile\u002Fintegrations](https:\u002F\u002Fwww.notion.so\u002Fprofile\u002Fintegrations)，创建一个新的**内部**集成，或选择一个已有的集成。\n\n![创建 Notion 集成令牌](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_0346fcd3f0f7.png)\n\n尽管我们限制了 Notion API 的公开范围（例如，您将无法通过 MCP 删除数据库），但将工作区数据暴露给 LLM 仍存在一定的风险。注重安全的用户可以进一步配置集成的_权限_。\n\n例如，您可以在“配置”选项卡中仅授予“读取内容”权限，从而创建一个只读集成令牌：\n\n![Notion 集成令牌权限，仅勾选“读取内容”](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_f40506137dd0.png)\n\n#### 2. 将内容连接到集成\n\n确保相关页面和数据库已连接到您的集成。\n\n为此，请访问内部集成设置中的**访问**选项卡。编辑访问权限，并选择您想要使用的页面。\n\n![集成访问选项卡](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_dc602f009cee.png)\n\n![编辑集成访问权限](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_90615fc52a97.png)\n\n或者，您也可以单独授予页面访问权限。您需要访问目标页面，点击右上角的三个点，然后选择“连接到集成”。\n\n![将集成令牌添加到 Notion 连接](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_2efae4a4fe76.png)\n\n#### 3. 在客户端中添加 MCP 配置\n\n##### 使用 npm\n\n###### Cursor 和 Claude\n\n将以下内容添加到您的 `.cursor\u002Fmcp.json` 或 `claude_desktop_config.json`（MacOS：`~\u002FLibrary\u002FApplication\\ Support\u002FClaude\u002Fclaude_desktop_config.json`）中。\n\n###### 选项 1：使用 NOTION_TOKEN（推荐）\n\n```json\n{\n  \"mcpServers\": {\n    \"notionApi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@notionhq\u002Fnotion-mcp-server\"],\n      \"env\": {\n        \"NOTION_TOKEN\": \"ntn_****\"\n      }\n    }\n  }\n}\n```\n\n###### 选项 2：使用 OPENAPI_MCP_HEADERS（适用于高级用例）\n\n```json\n{\n  \"mcpServers\": {\n    \"notionApi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@notionhq\u002Fnotion-mcp-server\"],\n      \"env\": {\n        \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\" }\"\n      }\n    }\n  }\n}\n```\n\n###### Zed\n\n将以下内容添加到您的 `settings.json` 中：\n\n```json\n{\n  \"context_servers\": {\n    \"some-context-server\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"-y\", \"@notionhq\u002Fnotion-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使用 Copilot CLI 以交互方式添加 MCP 服务器：\n\n```bash\n\u002Fmcp add\n```\n\n或者，创建或编辑配置文件 `~\u002F.copilot\u002Fmcp-config.json`，并添加：\n\n```json\n{\n  \"mcpServers\": {\n    \"notionApi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@notionhq\u002Fnotion-mcp-server\"],\n      \"env\": {\n        \"NOTION_TOKEN\": \"ntn_****\"\n      }\n    }\n  }\n}\n```\n\n有关更多信息，请参阅 [Copilot CLI 文档](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Fconcepts\u002Fagents\u002Fabout-copilot-cli)。\n\n##### 使用 Docker\n\n有两种方法可以使用 Docker 运行 MCP 服务器：\n\n###### 选项 1：使用官方 Docker Hub 镜像\n\n将以下内容添加到您的 `.cursor\u002Fmcp.json` 或 `claude_desktop_config.json` 中。\n\n使用 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\u002Fnotion\"\n      ],\n      \"env\": {\n        \"NOTION_TOKEN\": \"ntn_****\"\n      }\n    }\n  }\n}\n```\n\n使用 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\u002Fnotion\"\n      ],\n      \"env\": {\n        \"OPENAPI_MCP_HEADERS\": \"{\\\"Authorization\\\":\\\"Bearer ntn_****\\\",\\\"Notion-Version\\\":\\\"2025-09-03\\\"}\"\n      }\n    }\n  }\n}\n```\n\n这种方法：\n\n- 使用官方 Docker Hub 镜像\n- 通过环境变量正确处理 JSON 转义\n- 提供更可靠的配置方式\n\n###### 选项 2：在本地构建 Docker 镜像\n\n您也可以在本地构建并运行 Docker 镜像。首先，构建 Docker 镜像：\n\n```bash\ndocker compose build\n```\n\n然后，将以下内容添加到您的 `.cursor\u002Fmcp.json` 或 `claude_desktop_config.json` 中。\n\n使用 NOTION_TOKEN（推荐）：\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使用 OPENAPI_MCP_HEADERS（适用于高级用例）：\n\n```json\n{\n  \"mcpServers\": {\n    \"notionApi\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--rm\",\n        \"-i\",\n        \"-e\",\n        \"OPENAPI_MCP_HEADERS={\\\"Authorization\\\": \\\"Bearer ntn_****\\\", \\\"Notion-Version\\\": \\\"2025-09-03\\\"}\",\n        \"notion-mcp-server\"\n      ]\n    }\n  }\n}\n```\n\n请务必用您的集成密钥替换 `ntn_****`。您可以在集成配置选项卡中找到它：\n\n![从开发者门户的配置选项卡复制集成令牌](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_readme_c2e68bd90ee0.png)\n\n### 传输选项\n\nNotion MCP 服务器支持两种传输模式：\n\n#### STDIO 传输（默认）\n\n默认传输模式使用标准输入\u002F输出进行通信。这是大多数客户端（如 Claude Desktop）使用的标准 MCP 传输方式。\n\n```bash\n# 使用默认 stdio 传输运行\nnpx @notionhq\u002Fnotion-mcp-server\n\n# 或者显式指定 stdio\nnpx @notionhq\u002Fnotion-mcp-server --transport stdio\n```\n\n#### 可流式 HTTP 传输\n\n对于基于 Web 的应用程序或偏好 HTTP 通信的客户端，您可以使用可流式 HTTP 传输：\n\n```bash\n# 使用可流式 HTTP 传输，默认端口 3000\nnpx @notionhq\u002Fnotion-mcp-server --transport http\n\n# 使用自定义端口\nnpx @notionhq\u002Fnotion-mcp-server --transport http --port 8080\n\n# 使用自定义身份验证令牌运行\nnpx @notionhq\u002Fnotion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\n当使用可流式 HTTP 传输时，服务器将在 `http:\u002F\u002F0.0.0.0:\u003Cport>\u002Fmcp` 上可用。\n\n##### 身份验证\n\n为了安全起见，可流式 HTTP 传输需要使用 Bearer 令牌进行身份验证。您有三种选项：\n\n###### 选项 1：自动生成的令牌（仅用于开发）\n\n```bash\nnpx @notionhq\u002Fnotion-mcp-server --transport http\n```\n\n服务器将生成一个安全的随机令牌，并在控制台中显示：\n\n```text\n已生成的身份验证令牌：a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\n请在 Authorization 头部使用此令牌：Bearer a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab\n```\n\n###### 选项 2：通过命令行指定自定义令牌（推荐用于生产环境）\n\n```bash\nnpx @notionhq\u002Fnotion-mcp-server --transport http --auth-token \"your-secret-token\"\n```\n\n###### 选项 3：通过环境变量指定自定义令牌（推荐用于生产环境）\n\n```bash\nAUTH_TOKEN=\"your-secret-token\" npx @notionhq\u002Fnotion-mcp-server --transport http\n```\n\n如果同时提供了命令行参数 `--auth-token` 和 `AUTH_TOKEN` 环境变量，则命令行参数优先。\n\n##### 发送 HTTP 请求\n\n所有针对可流式 HTTP 传输的请求都必须在 Authorization 头部包含 Bearer 令牌：\n\n```bash\n# 示例请求\ncurl -H \"Authorization: Bearer your-token-here\" \\\n     -H \"Content-Type: application\u002Fjson\" \\\n     -H \"mcp-session-id: your-session-id\" \\\n     -d '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}' \\\n     http:\u002F\u002Flocalhost:3000\u002Fmcp\n```\n\n**注意：** 在使用任一传输模式时，请确保设置 `NOTION_TOKEN` 环境变量（推荐）或带有您的 Notion 集成令牌的 `OPENAPI_MCP_HEADERS` 环境变量。\n\n### 示例\n\n1. 使用以下指令：\n\n   ```text\n   在“入门”页面上评论“Hello MCP”\n   ```\n\n   AI 将正确规划两个 API 调用，即 `v1\u002Fsearch` 和 `v1\u002Fcomments`，以完成该任务。\n\n1. 类似地，以下指令将在父页面“开发”中添加一个名为“Notion MCP”的新页面：\n\n   ```text\n   在“开发”页面上添加一个标题为“Notion MCP”的页面\n   ```\n\n1. 您也可以直接引用内容 ID：\n\n   ```text\n   获取页面 1a6b35e6e67f802fa7e1d27686f017f2 的内容\n   ```\n\n### 开发\n\n#### 构建与测试\n\n```bash\nnpm run build\nnpm test\n```\n\n#### 执行\n\n```bash\nnpx -y --prefix \u002Fpath\u002Fto\u002Flocal\u002Fnotion-mcp-server @notionhq\u002Fnotion-mcp-server\n```\n\n在 Cursor 中本地测试更改：\n\n1. 从仓库根目录运行 `npm link` 命令，以创建指向 `notion-mcp-server` 包的全局符号链接。\n2. 将下面的配置片段合并到 Cursor 的 `mcp.json` 文件中（或您想要测试的其他 MCP 客户端）。\n3. （清理）从仓库根目录运行 `npm unlink`。\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#### 发布\n\n```bash\nnpm login\nnpm publish --access public\n```","# Notion MCP Server 快速上手指南\n\n## 环境准备\n\n在开始之前，请确保满足以下要求：\n\n*   **操作系统**：macOS, Linux 或 Windows (需安装 Node.js 环境)\n*   **运行时依赖**：\n    *   [Node.js](https:\u002F\u002Fnodejs.org\u002F) (推荐 v18 或更高版本)\n    *   `npx` (随 Node.js 自动安装)\n    *   或者使用 Docker (可选方案)\n*   **Notion 账号**：拥有管理员权限的工作区\n*   **AI 客户端**：支持 MCP 协议的客户端 (如 Cursor, Claude Desktop, Zed, GitHub Copilot CLI 等)\n\n> **⚠️ 重要提示**：本项目 (本地服务器) 未来可能停止维护。Notion 官方推荐使用基于 OAuth 的远程 **Notion MCP**。若需长期稳定使用，建议参考 [Notion 官方文档](https:\u002F\u002Fdevelopers.notion.com\u002Fdocs\u002Fmcp)。本指南仅针对当前开源的本地版本。\n\n## 安装步骤\n\n### 第一步：配置 Notion 集成\n\n1.  访问 [Notion 集成管理页面](https:\u002F\u002Fwww.notion.so\u002Fprofile\u002Fintegrations)。\n2.  点击 **+ New integration** 创建一个新的 **Internal integration** (内部集成)。\n3.  在 **Configuration** 标签页中：\n    *   复制 **Internal Integration Token** (格式为 `ntn_...`)，稍后配置时需要。\n    *   (可选) 为了安全，可在 **Capabilities** 中仅勾选 \"Read content\" 实现只读访问。\n4.  在 **Access** 标签页中：\n    *   点击 **Edit**，选择你需要让 AI 访问的页面或数据库。\n    *   或者，进入目标 Notion 页面，点击右上角 `···` -> **Connect to** -> 选择你刚创建的集成。\n\n### 第二步：配置 AI 客户端\n\n根据你的客户端类型，选择以下一种方式配置。请将 `\u003CYOUR_NOTION_TOKEN>` 替换为第一步中复制的 Token。\n\n#### 方案 A：Cursor \u002F Claude Desktop (推荐)\n\n编辑配置文件：\n*   **Cursor**: `.cursor\u002Fmcp.json` (项目根目录) 或全局配置\n*   **Claude Desktop**:\n    *   macOS: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n    *   Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n添加以下内容：\n\n```json\n{\n  \"mcpServers\": {\n    \"notionApi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@notionhq\u002Fnotion-mcp-server\"],\n      \"env\": {\n        \"NOTION_TOKEN\": \"\u003CYOUR_NOTION_TOKEN>\"\n      }\n    }\n  }\n}\n```\n\n#### 方案 B：Zed Editor\n\n编辑 `settings.json`：\n\n```json\n{\n  \"context_servers\": {\n    \"notionApi\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"-y\", \"@notionhq\u002Fnotion-mcp-server\"],\n        \"env\": {\n          \"NOTION_TOKEN\": \"\u003CYOUR_NOTION_TOKEN>\"\n        }\n      },\n      \"settings\": {}\n    }\n  }\n}\n```\n\n#### 方案 C：GitHub Copilot CLI\n\n运行交互式命令：\n```bash\n\u002Fmcp add\n```\n按提示输入，或手动编辑 `~\u002F.copilot\u002Fmcp-config.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"notionApi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@notionhq\u002Fnotion-mcp-server\"],\n      \"env\": {\n        \"NOTION_TOKEN\": \"\u003CYOUR_NOTION_TOKEN>\"\n      }\n    }\n  }\n}\n```\n\n#### 方案 D：Docker 运行\n\n如果你偏好容器化部署，可使用官方镜像：\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\u002Fnotion\"\n      ],\n      \"env\": {\n        \"NOTION_TOKEN\": \"\u003CYOUR_NOTION_TOKEN>\"\n      }\n    }\n  }\n}\n```\n\n## 基本使用\n\n配置完成后，重启你的 AI 编辑器或客户端。MCP 工具会自动加载，无需额外代码。\n\n### 核心功能变化 (v2.0+)\n版本 2.0 已将“数据库 (Database)\"抽象升级为“数据源 (Data Source)\"。旧的工具名称（如 `post-database-query`）已废弃，新工具包括 `query-data-source`, `create-a-data-source` 等。AI 会自动识别新工具，但若你在 Prompt 中硬编码了旧工具名，请更新为新名称。\n\n### 使用示例\n\n直接在对话框中使用自然语言指令即可：\n\n**示例 1：搜索并评论**\n> \"在 'Getting started' 页面上评论 'Hello MCP'\"\n> *(AI 将自动调用 search 和 comments 接口)*\n\n**示例 2：创建页面**\n> \"在 'Development' 页面下创建一个标题为 'Notion MCP' 的新页面\"\n\n**示例 3：查询内容**\n> \"获取页面 ID 为 1a6b35e6e67f802fa7e1d27686f017f2 的内容\"\n\n**示例 4：操作数据源 (原数据库操作)**\n> \"查询 'Project Tasks' 数据源中状态为 'Done' 的所有条目\"\n\n### 高级用法：HTTP 模式\n\n若需通过 HTTP 暴露服务（例如供 Web 应用调用），可使用 Streamable HTTP 传输模式：\n\n```bash\n# 启动 HTTP 服务 (默认端口 3000)\nnpx @notionhq\u002Fnotion-mcp-server --transport http --auth-token \"your-secret-token\"\n\n# 设置环境变量启动\nexport NOTION_TOKEN=\"\u003CYOUR_NOTION_TOKEN>\"\nexport AUTH_TOKEN=\"your-secret-token\"\nnpx @notionhq\u002Fnotion-mcp-server --transport http\n```\n\n服务地址：`http:\u002F\u002F0.0.0.0:3000\u002Fmcp`\n请求时需携带 Header: `Authorization: Bearer your-secret-token`","某初创公司的产品团队正利用 AI 助手自动整理每周用户反馈，并将其结构化归档至 Notion 知识库中。\n\n### 没有 notion-mcp-server 时\n- **手动复制粘贴繁琐**：开发人员需将 AI 生成的 Markdown 格式反馈报告手动复制并调整格式后填入 Notion 页面，极易出错且耗时。\n- **数据更新不同步**：当需要修改已归档的数据库条目时，必须人工查找对应 ID 并在后台操作，AI 无法直接执行更新指令。\n- **API 配置门槛高**：团队需手动管理复杂的 JSON 配置文件和 API Token，每次轮换密钥或新增权限都需重新部署本地服务。\n- **上下文切换频繁**：为了确认数据库结构（Schema），开发者需反复在代码、Notion 界面和 API 文档间切换，打断工作流。\n\n### 使用 notion-mcp-server 后\n- **一键自动化归档**：AI 代理直接调用 `create-a-data-source` 等工具，将生成的 Markdown 内容自动写入指定 Notion 数据库，无需人工干预。\n- **智能动态更新**：通过 `update-a-data-source` 工具，AI 可根据新反馈自动修正已有条目的属性或状态，保持数据实时准确。\n- **OAuth 免密集成**：借助标准 OAuth 流程快速安装，彻底告别手动配置 Token 和 JSON 文件的繁琐过程，安全性与便捷性大幅提升。\n- **自适应元数据感知**：AI 能自动调用 `retrieve-a-data-source` 获取最新的数据库结构，无需人工告知字段定义即可精准填充数据。\n\nnotion-mcp-server 通过标准化的工具链让 AI 真正“读懂”并“操作”Notion，将原本割裂的信息处理流程转化为全自动化的智能闭环。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmakenotion_notion-mcp-server_c2572672.png","makenotion","Notion","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fmakenotion_73b6570b.png","\"We shape our tools, thereafter our tools shape us\"",null,"team@makenotion.com","notionhq","https:\u002F\u002Fwww.notion.so","https:\u002F\u002Fgithub.com\u002Fmakenotion",[85,89,93],{"name":86,"color":87,"percentage":88},"TypeScript","#3178c6",99,{"name":90,"color":91,"percentage":92},"Dockerfile","#384d54",0.5,{"name":94,"color":95,"percentage":96},"JavaScript","#f1e05a",0.4,4153,531,"2026-04-03T03:42:37","MIT","Linux, macOS, Windows","不需要 GPU","未说明",{"notes":105,"python":106,"dependencies":107},"该工具是一个基于 Node.js 的 MCP 服务器，主要通过 npx 或 Docker 运行，无需 Python 环境。核心需求是有效的 Notion 集成令牌 (NOTION_TOKEN)。支持 STDIO 和 Streamable HTTP 两种传输模式。若使用 Docker，需安装 Docker 引擎。README 提到官方正在转向远程 MCP 服务，此本地仓库未来可能停止维护。","未说明 (通过 npx 运行，依赖 Node.js 环境)",[108,109,110],"Node.js","npm\u002Fnpx","@notionhq\u002Fnotion-mcp-server",[15,45],"2026-03-27T02:49:30.150509","2026-04-06T08:45:31.154902",[115,120,125,130,135,140],{"id":116,"question_zh":117,"answer_zh":118,"source_url":119},12057,"认证成功但服务器重连失败（Authentication successful, but server reconnection failed）怎么办？","如果您使用的是 Codex、Claude 等支持 MCP OAuth 客户端的工具，需要构建 MCP 客户端并通过客户端注册和授权流程获取远程服务器提供的 OAuth 访问令牌。直接通过 Notion 集成令牌连接远程服务器可能无法工作。请参考官方文档了解如何连接远程服务器：https:\u002F\u002Fdevelopers.notion.com\u002Fdocs\u002Fget-started-with-mcp","https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fissues\u002F167",{"id":121,"question_zh":122,"answer_zh":123,"source_url":124},12058,"使用 replace_content 或 replace_content_range 更新页面时，为什么子页面和数据库会被移动到回收站？","这是一个已知问题，现已添加安全防护机制。当操作会删除子内容时，工具会返回 validation_error 并列出受影响的子项，此时需要设置 allow_deleting_content 为 true 才能继续。\n重要提示：若要保留子内容，必须在 new_str 中使用原始 URL（raw URLs）引用它们，例如：\u003Cdatabase url=\"https:\u002F\u002Fwww.notion.so\u002FID\">Name\u003C\u002Fdatabase>。使用 fetch 返回的 {{...}} 格式 URL 或 \u003Cmention-*> 标签无法满足保护条件，仍会触发删除警告。此外，AI 在遇到验证错误时不应自动假设应删除内容，必须向用户展示待删除列表并请求确认。","https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fissues\u002F171",{"id":126,"question_zh":127,"answer_zh":128,"source_url":129},12059,"在 Cursor 或其他编辑器中调用 notion-update-page 失败或参数不正确怎么办？","如果官方版本存在此问题，可以尝试使用社区维护的 Fork 版本，该版本合并了相关修复补丁，已解决数据库 PostPage 和 UpdatePage 的问题。\nFork 地址：\n- GitHub: https:\u002F\u002Fgithub.com\u002Fmieubrisse\u002Fnotion-mcp-server\n- NPM: @mieubrisse\u002Fnotion-mcp-server\n注意：该 Fork 主要修复作者自己的工作流问题及合并其他人的 Bug 修复 PR，不处理新功能请求。","https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fissues\u002F131",{"id":131,"question_zh":132,"answer_zh":133,"source_url":134},12060,"运行时报错 'Headers is not defined' 如何解决？","该错误是因为部分 Node.js 版本未内置 Fetch API 中的 Headers 类。\n解决方案：\n1. 升级 Node.js 到支持全局 Headers 的版本；\n2. 或者使用 Docker 运行 Notion MCP Server，Docker 环境中通常已包含正确的运行时依赖，可避免此类兼容性问题。","https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fissues\u002F32",{"id":136,"question_zh":137,"answer_zh":138,"source_url":139},12061,"Claude Code 在使用 MCP 创建数据库条目时表现不稳定或失败怎么办？","Anthropic 团队上周已针对此问题发布了修复补丁，目前在 Claude Desktop 中应能正常工作。\n建议尝试以下方法：\n1. 确保您的 Claude Desktop 已更新到最新版本；\n2. 如果问题依旧，尝试切换不同的 LLM 模型进行测试；\n3. 若仍无法解决，可直接向 Claude 官方团队反馈此问题。","https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fissues\u002F74",{"id":141,"question_zh":142,"answer_zh":143,"source_url":144},12062,"配置了所有权限但仍提示 'no access to content' 或权限不足怎么办？","即使您在集成设置中勾选了所有权限，Notion 的工作空间权限机制可能仍然限制访问。MCP 可能需要显式访问特定页面的权限。\n建议检查：\n1. 确保集成已被添加到您想要访问的具体页面（点击页面右上角 '...' -> 'Connections' -> 添加您的集成）；\n2. 对于团队空间（Teamspaces），可能需要管理员在团队空间设置中授予集成访问所有页面的权限，而不仅仅是单个页面。","https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fissues\u002F6",[146],{"id":147,"version":148,"summary_zh":149,"released_at":150},62482,"v2.1.0","## 变更内容\n\n* @ksinder 在 https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fpull\u002F170 中对包文件和 README 进行了小幅修复和清理\n* 功能：添加工具注释，以提升大模型对工具的理解，由 @bryankthompson 在 https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fpull\u002F169 中实现\n* 修复：处理来自 MCP 客户端的双重序列化 JSON 参数，由 @pwarnock 在 https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fpull\u002F180 中完成\n* 文档：添加 GitHub Copilot CLI 的安装说明，由 @GeekTrainer 在 https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fpull\u002F190 中完成\n* 修复：保留常量值，并允许页面模式中包含任意属性，由 @danielostrow 在 https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fpull\u002F173 中实现\n* 提案：增加一个禁用认证头的选项，由 @piljaechae 在 https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fpull\u002F105 中提出\n* 功能：在 OpenAPI 规范中添加检索数据库的端点，由 @ksinder 在 https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fpull\u002F195 中实现\n\n## 新贡献者\n\n* @bryankthompson 在 https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fpull\u002F169 中完成了首次贡献\n* @pwarnock 在 https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fpull\u002F180 中完成了首次贡献\n* @GeekTrainer 在 https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fpull\u002F190 中完成了首次贡献\n* @danielostrow 在 https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fpull\u002F173 中完成了首次贡献\n* @piljaechae 在 https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fpull\u002F105 中完成了首次贡献\n\n## 链接\n\n- **完整变更日志**: https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-mcp-server\u002Fcompare\u002Fv2.0.0...v2.1.0\n- **NPM 包**: https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@notionhq\u002Fnotion-mcp-server\u002Fv\u002F2.1.0","2026-01-31T18:27:31"]