AI导哈

Notion集成MCP服务器

一个独立的MCP服务器，使AI助手（如Claude Desktop、VAPI等）能够通过结构化工具调用与Notion工作区交互。

  • by azank1
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 azank1/notion-mcp

使用说明

通知代理MCP服务器

用于Notion工作空间集成的模型上下文协议（MCP）服务器。

概述

独立的MCP服务器，使AI助手（Claude Desktop、VAPI等）能够通过结构化的工具调用与Notion工作区进行交互。

状态：MVP开发
版本：0.1.0-mvp
集成：隔离（尚未与MetaOrcha平台集成）

特性

已实施的工具

  • 创建页面 -创建具有丰富格式内容的Notion页面

计划工具

  • update_page -更新现有页面内容和属性
  • 查询数据库 -使用过滤器和排序查询Notion数据库
  • 搜索 -在工作区中搜索页面和数据库
  • add_chart -在页面中嵌入TradingView图表

安装

# Clone repository
git clone https://github.com/azank1/notion-agent-mcp.git
cd notion-agent-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env and add your NOTION_API_KEY

# Build project
npm run build

配置

环境变量

创建一个 .env 文件：

# Required
NOTION_API_KEY=secret_your_notion_integration_key

# Optional
PORT=3003
NODE_ENV=development
LOG_LEVEL=info

获取Notion API密钥

  1. 首选https://www.notion.so/my-integrations
  2. 点击“+新集成”
  3. 将其命名为“MCP Agent”并选择您的工作区
  4. 复制“内部集成令牌”
  5. 通过集成共享您的数据库/页面

用法

发展模式

npm run dev

生产模式

npm run build
npm start

测试

# Run all tests
npm test

# Watch mode
npm run test:watch

# Integration tests (requires real Notion workspace)
npm run test:integration

与Claude Desktop一起使用

  1. 构建项目：

    npm run build

  2. 编辑Claude桌面配置：

    macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    Linux: ~/.config/Claude/claude_desktop_config.json
    视窗: %APPDATA%\Claude\claude_desktop_config.json

  3. 添加MCP服务器：

    {
  "mcpServers": {
    "notion-research": {
      "command": "node",
      "args": ["/path/to/notion-agent-mcp/dist/index.js"],
      "env": {
        "NOTION_API_KEY": "secret_your_notion_api_key"
      }
    }
  }
}

  4. 重新启动克劳德桌面

  5. 测试一下：

    "Create a research note about Bitcoin in my Notion workspace"

API文档

创建页面

创建内容丰富的新Notion页面。

参数:

  • title （字符串，必填）：页面标题
  • parentId （字符串，必填）：父数据库或页面ID
  • content （数组，可选）：内容块
  • properties （对象，可选）：其他Notion属性

示例:

{
  "title": "Research Note: Bitcoin",
  "parentId": "your-database-id-here",
  "content": [
    {
      "type": "heading_1",
      "content": "Overview"
    },
    {
      "type": "paragraph",
      "content": "Bitcoin is a decentralized cryptocurrency..."
    },
    {
      "type": "bulleted_list_item",
      "content": "Launched in 2009"
    }
  ]
}

发展

项目结构

notion-agent-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server implementation
│   ├── config/               # Configuration
│   ├── types/                # TypeScript types
│   ├── notion/               # Notion API client
│   └── tools/                # MCP tools
│       ├── create-page.ts
│       └── index.ts
├── tests/                    # Test files (planned)
├── package.json
├── tsconfig.json
└── README.md

分支策略

单分支开发 main MVP阶段。将根据需要创建功能分支，与metaorcha控制和metaorcha emerge存储库工作流保持一致。

添加新工具

  1. 在中创建工具文件 src/tools/your-tool.ts
  2. 执行工具功能
  3. 导出工具定义（MCP模式）
  4. 添加到 src/tools/index.ts
  5. 在中添加测试 tests/unit/tools/

测试

单元测试

在不影响Notion API的情况下测试单个工具：

npm test -- create-page.test.ts

集成测试

使用真实的Notion工作空间进行测试：

# Set up test database
export TEST_NOTION_DATABASE_ID=your-test-db-id

# Run integration tests
npm run test:integration

部署

铁路（建议MVP使用）

# Install Railway CLI
npm install -g @railway/cli

# Login and init
railway login
railway init

# Set environment variables in Railway dashboard
# Deploy
railway up

MVP状态

  • [x] 项目设置和TypeScript配置
  • [x] MCP协议实现
  • [x] 通知API客户端
  • [x] create_page工具
  • []update_page工具
  • []查询数据库工具
  • []搜索工具
  • []add_chart工具
  • []单元测试（80%覆盖率）
  • []集成测试
  • []克劳德桌面测试
  • []铁路部署
  • []性能基准

与MetaOrcha集成

状态：在MVP完成之前被阻止

这种试剂是单独开发的。与MetaOrcha编排平台的集成将在MVP验证和规范批准后进行。

看 METAORCHA_INTEGRATION.md 了解详情。

贡献

看 贡献.md 发展指南。

许可证

麻省理工学院

问题

报告问题：https://github.com/azank1/notion-agent-mcp/issues

相关 MCP