AI Notion Agent

🧠 AI Notion Agent

Welcome to the AI Notion Agent! This repository provides an intelligent agent that can interact with, read from, and write to your personal Notion workspace using Natural Language.

This project is a raw REST API designed for developers who want to integrate the Notion Agent into their own applications, scripts, or workflows programmatically. It runs on a local Flask server and is exposed to the public internet securely using an Ngrok tunnel, demonstrating advanced usage of the Model Context Protocol (MCP).

---

🛠️ Developer REST API (Local Tunneled via Ngrok)

Prerequisites

You must have a Notion Integration Token (e.g. ntn_...) added to your .env file to grant the agent permission to interact with your workspace.

How to get your Notion API Key:

1. Go to the Notion Developer Portal (My Integrations).
2. Click New integration.
3. Give it a name (e.g., "AI Agent") and select your workspace.
4. Copy the "Internal Integration Secret" token (ntn_...) and paste it into your .env file as NOTION_API_KEY.
5. Crucial Step: Go to the Notion pages or workspace you want the agent to access, click the ... menu in the top right, click Connect to, and select your new integration.

How to get your Ngrok Auth Token:

1. Create a free account or log in at Ngrok.
2. On your dashboard, navigate to Getting Started > Your AuthToken (or go directly to this link).
3. Copy your Auth Token and paste it into your .env file as NGROK_AUTH_TOKEN.

> Why are we using Ngrok? > Strictly speaking, if you are only running this agent locally on your own laptop, you do not need Ngrok. The Streamlit frontend and Flask backend could communicate over localhost. However, this project is designed to simulate a real-world, decoupled AI architecture. By using Ngrok, you are exposing your custom MCP server to the public internet securely. This means that in the future, any remote AI Agent in the cloud (like ChatGPT or Claude) could connect to your local Notion server over the internet, demonstrating true interoperability.

How to use the agent (User-Friendly Interface):

For the best experience, use the provided Streamlit Web UI.

1. Ensure your backend server is running in a terminal:

``bash python notion_agent_final.py ``

1. Note the Ngrok URL printed in the terminal (e.g., https://xyz.ngrok-free.app).
2. Open app.py and update the FLASK_URL variable to match your new Ngrok URL.
3. Open a second terminal and run the Streamlit app:

``bash streamlit run app.py ``

1. A browser window will open automatically. Simply type your natural language task (e.g., "Create a new page titled My Next Big Idea") and click Run Task.

---

🛠️ Developer REST API (Local Tunneled via Ngrok)

If you prefer to integrate the agent programmatically instead of using the UI, you can use the REST API.

How to run the API:

1. Make sure you have your .env file configured in the project root:

``dotenv OPENAI_API_KEY=your_openai_key NOTION_API_KEY=your_oauth_notion_key NGROK_AUTH_TOKEN=your_ngrok_auth_token ``

1. Run the main server script:

``bash python notion_agent_final.py ``

1. The terminal will provide you with a public Ngrok URL (e.g., https://xyz.ngrok-free.app/api/hello).

How to consume the API:

Send a POST request to the generated Ngrok endpoint at the /run path with your task in the JSON body:

curl -X POST https://[your-ngrok-url]/run \
     -H "Content-Type: application/json" \
     -d '{
           "task": "Create a new page titled My Next Big Idea"
         }'

Response:

{
  "status": "sucess",
  "result": "I have successfully created a new page titled \"My Next Big Idea\"..."
}

---

🚀 Future Use Case: Connecting to Cloud AI (like ChatGPT)

Because this project exposes the agent as a public REST API via Ngrok, the architecture is completely decoupled. This means the agent can be plugged into cloud AI platforms like ChatGPT.

How this works with ChatGPT Custom Actions:

1. The server is kept running locally (e.g., https://my-agent.ngrok.app).
2. A "Custom GPT" is created on OpenAI, providing an OpenAPI Schema that describes the /run endpoint.
3. A user types a prompt to ChatGPT: "Create a Notion page about my new startup."
4. ChatGPT (in the cloud) sends an HTTP POST request to the Ngrok URL.
5. The local AutoGen agent executes the Notion tools and creates the page.
6. ChatGPT reads the success response and replies to the user.

This demonstrates an "Agent-as-a-Service" model that can be utilized by external software!

Architecture details:

• The AI Agent (The MCP Client): Using Microsoft AutoGen, this project builds an AI Agent. The agent connects to the Notion MCP server, reads the available tools, and decides how to use them based on the user's natural language request. In MCP terminology, the AutoGen agent acts as an MCP Client.
• Framework: Flask, Asyncio
• Tunneling: PyNgrok
• Files used: notion_agent_final.py

---

Tech Stack

• AI Framework: Autogen (Microsoft)
• Protocol: Model Context Protocol (MCP) by Anthropic for Notion integration.
• LLM: OpenAI GPT-4o-mini
• Web Backend: Flask

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: urmikanrar2003-uk
• Source: urmikanrar2003-uk/AINotion_Agent
• License: MIT

Install and usage instructions live in the source repository linked above.