NotionMCP — AI-Powered Notion Assistant via MCP

NotionMCP — AI-Powered Notion Assistant via MCP

NotionMCP is a Modular Context Protocol (MCP) server that exposes advanced Notion search, reading, summarization, and emotion-analysis tools to any MCP-compatible LLM client such as Claude Desktop.

This project turns your Notion workspace into an intelligent, queryable knowledge system, giving your AI assistant the ability to:

• Search pages and databases with precision
• Read and extract block-level content
• Summarize large or complex Notion pages
• Analyze sentiment/emotion of page text
• Build AI workflows on top of your Notion data
• Operate securely using the MCP standard

It is built for:

• Developers
• Researchers
• Data science teams
• Knowledge-intensive organizations
• Anyone wanting an AI agent deeply integrated with Notion

Features

Intelligent Notion Search

• Title search
• Page/database filtering
• Pagination + streaming search
• User discovery tools

Advanced Content Reading

• Extract readable text from pages
• Traverse block structures
• Read pages by name or ID
• Support for headings, lists, checkboxes, callouts, quotes, etc.

AI Summaries & Emotion Analysis

• Abstractive summarization (T5)
• Emotion/tone classification (Transformers)
• Integrated into Notion workflows

Fully MCP-Compatible

Works out-of-the-box with:

• Claude Desktop
• ChatGPT MCP mode
• Any MCP-compatible automation or agent

Clean, Modular Architecture

• search_tools.py
• read_tools.py
• ai_tools.py
• Async Notion client layer with retries + rate-limit handling

Business Value

NotionMCP upgrades Notion from a documentation space into a scalable AI knowledge engine.It enables teams and organizations to operate faster, reduce manual overhead, and make better decisions by turning unstructured notes into actionable intelligence.

For Organizations

• Automate summarization, research, onboarding, and documentation workflows
• Improve knowledge accessibility across teams and departments
• Standardize how information is consumed, summarized, and shared
• Reduce operational time spent searching or rewriting content
• Build internal AI agents capable of retrieving, processing, and analyzing company knowledge

For Technical Teams

• Gain a robust async Notion API client with retry + backoff handling
• Extend MCP tools with custom AI models or internal logic
• Integrate Notion into broader AI, analytics, or automation pipelines
• Build reproducible and automated workflows on top of Notion pages
• Maintain full control over data by running tools locally

Strategic Outcomes

• Faster decision-making
• Reduced cognitive load across technical and non-technical teams
• Stronger organizational memory and knowledge consistency
• A foundation for deployable AI assistants operating on real company data

Demo

Video Demo

Click to view ./demo/1.mp4

Image Walkthrough

Installation

You may install using either:

Option A — Using venv (recommended for most users)

1. Clone the repository

git clone https://github.com/DeepActionPotential/NotionMCP.git
cd NotionMCP

2. Create and activate a virtual environment

python -m venv .venv

Activate it:

Windows

.venv\Scripts\activate

macOS/Linux

source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Run the MCP server

python server.py

Option B — Installation using uv

uv sync
uv run server.py

Configuring Claude Desktop

Add the following to:

claude_desktop_config.json

{
  "mcpServers": {
    "NotionMCPServer": {
      "command": "uv",
      "args": [
        "--directory",
        "your-own-server-file-directory",
        "run",
        "server.py"
      ]
    }
  }
}

Restart Claude Desktop.You should now see all Notion tools available under the MCP Tools menu.

Environment Variables

Create a .env file or export environment variables:

NOTION_API_KEY=secret_notion-api
HTTP-TIMEOUT=60

Your Notion integration must be shared with the pages or workspace you want to read.

Usage Examples

Ask Claude:

• “Search Notion for pages about convolution.”
• “Summarize the Deep Learning page in 200 words.”
• “Extract the first 20 lines of the Metrics page.”
• “Analyze the emotional tone of the Vision page.”

Claude will automatically call MCP tools such as:

• search
• iter_search
• get_page_text
• summarize_page_text
• get_page_sentiment

Architecture

NotionMCP
│
├── tools/
│   ├── search_tools.py
│   ├── read_tools.py
│   └── ai_tools.py
│
├── core/
│   └── notion_clients.py
│
├── services/
│   ├── summarization_service.py
│   └── text_emotion_service.py
│
├── demo/
│
└── server.py

Contributing

Contributions are welcome:

• New AI models
• Additional Notion endpoints
• Performance improvements
• New MCP tools

Please open an issue or submit a PR.

License

MIT License — free for commercial and private use.