Notion MCP Agent

An AI-powered terminal agent that helps you interact with your Notion pages using natural language. This project provides two implementations: one powered by Google Gemini and another by OpenAI's GPT-4.

📋 Table of Contents

• Overview
• Features
• Prerequisites
• Installation & Setup
• Configuration
• Usage
• Commands
• Project Structure
• Troubleshooting

🎯 Overview

This project enables you to interact with your Notion workspace through an intelligent AI agent that runs in your terminal. Instead of manually navigating Notion, you can use natural language commands to:

• Read page content
• Search for information
• Add new content or update existing content
• Create lists, tables, and other Notion blocks
• Explain page structure
• Add comments to specific blocks

The agent maintains conversation history and remembers your interactions within a session, making it feel like a natural conversation with an assistant that understands your Notion workspace.

Technology Stack

• Framework: Agno (AI Agent framework)
• AI Models:
  • Google Gemini 2.5 Flash (via notion_mcp_agent_gemini.py)
  • OpenAI GPT-4 (via notion_mcp_agent_openai.py)
• Integration: Model Context Protocol (MCP) for Notion
• Database: SQLite for conversation history and memory
• Language: Python 3.8+

✨ Features

✅ AI-Powered Notion Interaction - Natural language interface to your Notion pages
✅ Conversation Memory - Maintains context across multiple interactions within a session
✅ Dual AI Model Support - Choose between Google Gemini or OpenAI
✅ Interactive CLI - User-friendly terminal interface with streaming responses
✅ Session Management - Unique user and session IDs for tracking
✅ Error Handling - Graceful error handling with helpful messages
✅ MCP Integration - Full Notion API access through Model Context Protocol

📦 Prerequisites

Before you start, make sure you have:

1. Python 3.8 or higher - Download Python
2. Node.js and npm - Required for running the Notion MCP server (Download Node.js)
3. Notion Account with:
   • At least one page you want to interact with
   • A Notion Integration token
4. AI API Key (choose one or both):
   • Google Gemini API key (for the Gemini version)
   • OpenAI API key (for the OpenAI version)

🚀 Installation & Setup

Step 1: Clone the Repository

git clone https://github.com/KushalParikh/notion-mcp-agent.git
cd notion-mcp-agent

Step 2: Create a Python Virtual Environment (Recommended)

Creating a virtual environment isolates dependencies for this project.

On Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1

On Windows (Command Prompt):

python -m venv venv
venv\Scripts\activate.bat

On macOS/Linux:

python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

This will install:

• agno - AI Agent framework
• python-dotenv - For environment variable management
• mcp - Model Context Protocol
• openai - OpenAI API client (for GPT-4 version)
• google-generativeai - Google Gemini API client (for Gemini version)
• sqlalchemy - Database ORM

⚙️ Configuration

Step 1: Create Environment Variables

Copy the example environment file and fill in your API keys:

cp .env.example .env

Then edit .env with your actual keys:

For the OpenAI Version:

NOTION_API_KEY=your_notion_integration_token_here
OPENAI_API_KEY=your_openai_api_key_here

For the Gemini Version:

NOTION_API_KEY=your_notion_integration_token_here
GOOGLE_API_KEY=your_google_gemini_api_key_here

For Both (Recommended):

NOTION_API_KEY=your_notion_integration_token_here
OPENAI_API_KEY=your_openai_api_key_here
GOOGLE_API_KEY=your_google_gemini_api_key_here

Step 2: Get Your Notion Integration Token

1. Go to Notion Integrations
2. Click "Create new integration"
3. Name your integration (e.g., "MCP Agent")
4. Select capabilities you need
5. Copy the "Internal Integration Secret" and use it as NOTION_API_KEY

Step 3: Get Your Notion Page ID

You need the ID of the Notion page you want to interact with:

1. Open your Notion page in a browser
2. Look at the URL in the address bar
3. The URL format is: https://www.notion.so/workspace/Your-Page-1f5b8a8ba283...
4. The Page ID is the long alphanumeric string at the end (after the last dash)
   • Example: 1f5b8a8ba28341e1a8b7c9d2e3f4g5h6

Step 4: Get Your AI API Key

For Google Gemini:

1. Go to Google AI Studio
2. Click "Create API Key"
3. Copy the API key and use it as GOOGLE_API_KEY

For OpenAI:

1. Go to OpenAI API Keys
2. Click "Create new secret key"
3. Copy the API key and use it as OPENAI_API_KEY

📖 Usage

Starting the Agent

Choose which AI model you want to use:

Option 1: Using Google Gemini

python notion_mcp_agent_gemini.py [page_id]

Option 2: Using OpenAI GPT-4

python notion_mcp_agent_openai.py [page_id]

With Page ID as Argument (Optional):

# Directly pass your page ID to skip the prompt
python notion_mcp_agent_openai.py 1f5b8a8ba28341e1a8b7c9d2e3f4g5h6

Without Page ID (Interactive Prompt):

# The agent will ask you to enter your page ID interactively
python notion_mcp_agent_openai.py

Interactive Session Example

Once the agent starts, you'll see:

========================================
      Notion MCP Terminal Agent
========================================

User ID: user_a1b2c3d4
Session ID: session_x9y8z7w6

Connecting to Notion MCP server...

Connected to Notion MCP server successfully!

Notion MCP Agent is ready! Start chatting with your Notion pages.

Type 'exit' or 'quit' to end the conversation.

You: What's on my page?
🤖: [Agent responds with information from your Notion page]

You: Add a new task: Buy groceries
🤖: [Agent adds the task to your page]

You: exit
[Session ends]

💻 Commands

Terminal Commands

| Command | Description | | -------------------------------------------------- | -------------------------------------------- | | python notion_mcp_agent_openai.py | Start the OpenAI version of the agent | | python notion_mcp_agent_gemini.py | Start the Google Gemini version of the agent | | python notion_mcp_agent_openai.py 1f5b8a8ba28... | Start with a specific Notion page ID | | pip install -r requirements.txt | Install all dependencies | | deactivate | Deactivate the virtual environment |

In-Agent Commands

| Command | Description | | --------- | ---------------------------------------- | | exit | End the conversation and close the agent | | quit | Same as exit | | bye | Same as exit | | goodbye | Same as exit |

Agent Instructions

Once the agent is running, you can ask it to:

• Read Content: "What's on my page?"
• Search: "Find all tasks with 'urgent' in the title"
• Add Content: "Add a new section called 'Q1 Goals'"
• Update Content: "Change the deadline to next Friday"
• Organize: "Create a table with columns: Task, Priority, Due Date"
• Explain: "Explain the structure of my page"

📁 Project Structure

notion-mcp-agent/
│
├── notion_mcp_agent_openai.py       # Agent using OpenAI GPT-4
├── notion_mcp_agent_gemini.py       # Agent using Google Gemini
├── requirements.txt                 # Python dependencies
├── .env.example                     # Environment template (copy to .env)
├── .gitignore                       # Git ignore rules
├── README.md                        # This file
│
├── .env                             # Your API keys (git-ignored, create this)
├── agno.db                          # SQLite database (git-ignored, auto-created)
└── venv/                            # Virtual environment (git-ignored)

File Descriptions

• notion_mcp_agent_openai.py: The main implementation using OpenAI's GPT-4 model. Provides the most powerful AI responses.
• notion_mcp_agent_gemini.py: Alternative implementation using Google's Gemini 2.5 Flash model. Lighter weight and faster responses.
• requirements.txt: Lists all Python package dependencies needed to run the project.
• .env: Configuration file where you store your API keys and tokens (create this yourself).
• agno.db: SQLite database that stores conversation history and agent memory (created automatically on first run).

🔧 Troubleshooting

Issue: "GOOGLE_API_KEY not found in .env file"

Solution:

• Make sure you created the .env file in the project root directory
• Add GOOGLE_API_KEY=your_key_here to the file
• Restart the agent

Issue: "Page ID is required"

Solution:

• Make sure you provided a valid Notion page ID
• Extract the ID correctly from your Notion URL
• Try running: python notion_mcp_agent_openai.py your_page_id

Issue: "ModuleNotFoundError: No module named 'agno'"

Solution:

• Make sure your virtual environment is activated
• Run: pip install -r requirements.txt
• Verify installation with: pip list

Issue: "Connection to Notion MCP server failed"

Solution:

• Make sure Node.js is installed: node --version
• Check your NOTION_API_KEY is correct
• Make sure the Notion integration has access to your page
• Try running with a different page ID

Issue: "Permission denied" on the page

Solution:

• Go back to your Notion Integration settings
• Make sure the integration has access to the database/page you're trying to access
• It might be a child page - try sharing it with the integration at the parent level

Issue: Running on Windows PowerShell shows encoding errors

Solution:

$env:PYTHONIOENCODING = "utf-8"
python notion_mcp_agent_openai.py

🎓 Quick Start Summary

1. Install Python (3.8+)
2. Clone/download this project
3. Create virtual environment: python -m venv venv + activate it
4. Install dependencies: pip install -r requirements.txt
5. Get API keys: Notion token, OpenAI/Gemini key
6. Create .env file with your keys
7. Get your Notion page ID from the page URL
8. Run the agent: python notion_mcp_agent_openai.py
9. Start chatting with your Notion page!

📝 Notes

• The agent stores conversation history in agno.db for better context understanding
• Each session generates unique User ID and Session ID for tracking
• The agent uses retries (up to 3 times) to handle API failures gracefully
• Conversation history from the last 5 interactions is included for context
• Both implementations (OpenAI and Gemini) share the same core functionality

❓ Need Help?

If you encounter issues:

1. Check the Troubleshooting section above
2. Verify all API keys and tokens are correctly set in .env
3. Make sure Node.js is installed on your system
4. Try the alternative AI model (switch between OpenAI and Gemini)
5. Check that your Notion integration has proper permissions

📜 License

This project is provided as-is for personal use.

Happy Notion automation! 🚀