🤖 Notion Agent Hub

AI Agent Hub for Notion — orchestrate AI agents through Notion databases with human-in-the-loop approval. Built with MCP.

<!-- Hero Banner --> <div align="center">

Turn your Notion workspace into an AI command center.

Quick Start · Architecture · Tools · Agents · Setup Guide

</div>

---

✨ What It Does

Notion Agent Hub is an MCP server that connects AI assistants (Claude, GPT, etc.) to your Notion workspace. It provides:

1. 🔍 Research Agent — Search the web, compile findings, and write structured research pages to Notion
2. 🔄 GitHub Tracker — Monitor GitHub PRs and sync their status to a Notion database
3. 📝 Content Pipeline — Read outlines from Notion, generate drafts, and submit for human review

All tasks flow through a Notion-native task queue with human-in-the-loop approval — you stay in control.

🏗 Architecture

graph TB
    subgraph "AI Assistant"
        C[Claude / GPT / etc.]
    end

    subgraph "MCP Server — notion-agent-hub"
        direction TB
        S[Server Entry Point]

        subgraph "Tools Layer"
            NR[📖 notion-read]
            NW[✏️ notion-write]
            NQ[🔎 notion-query]
            WS[🌐 web-search]
            CR[💻 code-run]
        end

        subgraph "Agent Layer"
            RA[🔬 Research]
            GT[🔄 GitHub Tracker]
            CP[📝 Content Pipeline]
        end

        TQ[📋 Task Queue]
    end

    subgraph "Your Notion Workspace"
        TD[(Task Database)]
        RP[Research Pages]
        DP[Draft Pages]
        PR[(PR Tracker DB)]
    end

    C <-->|MCP Protocol| S
    S --> NR & NW & NQ & WS & CR
    TQ -->|Poll| TD
    RA -->|Write| RP
    GT -->|Sync| PR
    CP -->|Write| DP
    TD -->|Human creates tasks| TQ

🚀 Quick Start

1. Clone & Install

git clone https://github.com/tysoncung/notion-agent-hub.git
cd notion-agent-hub
npm install

2. Configure

cp .env.example .env

Edit .env with your keys:

NOTION_API_KEY=ntn_your_integration_secret
NOTION_DATABASE_ID=your_task_database_id
OPENAI_API_KEY=sk-your_openai_key  # Optional

📖 See the Setup Guide for detailed instructions on creating a Notion integration and task database.

3. Build & Run

npm run build
npm start

4. Connect to Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "notion-agent-hub": {
      "command": "node",
      "args": ["/path/to/notion-agent-hub/dist/index.js"],
      "env": {
        "NOTION_API_KEY": "ntn_your_key",
        "NOTION_DATABASE_ID": "your_db_id"
      }
    }
  }
}

🛠 Tools

notion-read

Read pages, databases, and blocks from Notion.

Input:  { page_id?: string, database_id?: string, block_id?: string }
Output: Page content with properties and child blocks

notion-write

Create or update Notion pages with rich content.

Input:  { action: "create" | "update" | "append", parent_id?, page_id?, title?, blocks? }
Output: { id, url, created/updated/appended: true }

Supported block types: paragraph, heading_1/2/3, bulleted_list_item, numbered_list_item, toggle, quote, callout, divider, code

notion-query

Query databases with filters and sorting.

Input:  { database_id, filter?, sorts?, page_size? }
Output: { results: [...pages], has_more, next_cursor }

web-search

Search the web using Brave Search (or DuckDuckGo fallback).

Input:  { query: string, count?: number }
Output: { results: [{ title, url, snippet }], source }

code-run

Execute JavaScript in a sandboxed environment (Node.js vm module).

Input:  { code: string, timeout_ms?: number }
Output: { success, result?, stdout, stderr }

🤖 Agent Workflows

🔬 Research Agent

Input: Topic + parent page ID
Process: Web search → compile sources → create structured Notion page
Output: Research page with sources, findings, and review checklist

🔄 GitHub Tracker

Input: GitHub repo + Notion database ID
Process: Fetch PRs → compare with existing entries → create/update pages
Output: Synced PR database in Notion

📝 Content Pipeline

Input: Outline page ID + parent page ID
Process: Read outline → (optional research) → generate draft → create page
Output: Draft page with review checklist, ready for human editing

🔄 Human-in-the-Loop

The task queue uses your Notion database as the control plane:

You create a task          →  Status: Pending
Agent picks it up          →  Status: Running
Agent writes results       →  Status: Done ✅
Something went wrong?      →  Status: Failed ❌ (with error details)

You're always in control. Tasks only run when you create them. Results are always written back to Notion for your review.

Task Database Schema

Property	Type	Description
Name	Title	Task description
Status	Status	Pending → Running → Done/Failed
Type	Select	research / github-tracker / content-pipeline
Input	Text	JSON input parameters
Output	Text	JSON results
Error	Text	Error message (if failed)

📸 Demo

<!-- TODO: Add demo GIF showing the workflow -->

🧪 Development

# Run tests
npm test

# Watch mode
npm run test:watch

# Type checking
npm run lint

# Build
npm run build

# Dev mode (watch + rebuild)
npm run dev

📜 License

MIT — see LICENSE.

---

<div align="center">

Built for the Notion MCP Challenge 🏆

Powered by Model Context Protocol

</div>