# Notion MCP

> Notion MCP Server connects your entire Notion workspace—databases, pages, and blocks—directly to your AI agent. Instead of jumping into Notion just to find a piece of data or update a status, your agent can search across all databases, pull page contents, and edit properties using natural conversation. It's like giving your chat client read/write access to your entire knowledge base without opening the app.

## Overview
- **Category:** industry-titans
- **Price:** Free
- **Tags:** workspace-management, database-query, page-editing, knowledge-base, block-properties, content-management

## Description

Yo, this Notion MCP Server hooks up your whole Notion workspace—every database, every page, every block—straight into your AI agent. You don't gotta open a browser tab or manually copy-paste anything anymore; your agent handles it all through natural chat conversation. It’s like giving your client read/write access to the entire knowledge base without even opening the app.

**Finding What You Need:**

To find pages or databases, you just use **`search`**. It quickly locates anything in your workspace by matching title keywords. If you need a full inventory of data sources first, run **`list_databases`** to get a list of every database available for querying across the whole thing. You can also pull lists of people using **`list_users`**, and if you know who you're looking for, **`retrieve_user`** gets detailed info on any specific user by their ID.

**Digging Deep into Data:**

The server handles reporting with **`query_database`**. You can run advanced queries against specific databases; this lets you filter and sort records based on any property you want. Need to know what a database looks like before querying it? Use **`retrieve_database`** to fetch the full schema and metadata for that specific database ID, so you understand its structure. For reading content, use **`retrieve_page`**. This tool grabs all the raw content from a single Notion page if you know its unique ID. If you just need to see what blocks are nested inside a page or another block, run **`retrieve_block_children`**.

**Editing and Building Stuff:**

You don't just read; you write back. To change metadata on an existing entry—like flipping a status field from 'To Do' to 'Done,' or changing who owns a page—you use **`update_page`**. For building new knowledge entries, the agent uses **`create_page`** to build and save entirely new pages into your workspace; you gotta specify the parent and all the properties it needs. When you need to add content blocks to an existing block or whole page, **`append_block_children`** handles that for you.

**The Bottom Line:**

Your agent doesn't just pull data; it manages your knowledge base. You can ask it to find a record using **`search`**, then run reports on it with **`query_database`**. If the results are complex, you use **`retrieve_page`** to get all the content. Then, if that info is stale, you tell it to update the owner or status via **`update_page`**. You can even build out brand new sections using **`create_page`**, and then append specific blocks of text or images using **`append_block_children`**.

It’s all about making Notion act like a backend API you talk to naturally. Your agent doesn't just read the data; it uses the whole suite—from getting connection status with **`get_me`** to pulling user lists and detailed records using **`retrieve_user`**—to make sure your entire workflow stays inside chat, period.

## Tools

### append_block_children
Adds new content blocks to the end of an existing block or page.

### create_page
Builds a brand new page in your Notion workspace, requiring you to specify its parent and properties.

### get_me
Retrieves basic information about the current AI agent connection or integration status.

### list_databases
Provides a list of all databases available for querying in your entire workspace.

### list_users
Pulls a comprehensive list of every user account within the connected Notion workspace.

### query_database
Runs advanced queries against specific databases, allowing you to filter and sort records by any property.

### retrieve_block_children
Gets a list of all nested blocks (text, images, lists) contained within another block or page.

### retrieve_database
Fetches the schema and metadata for a specific database ID, helping you understand its structure.

### retrieve_page
Grabs all content from a single Notion page if you know its unique ID.

### retrieve_user
Retrieves detailed information about a specific user by their ID.

### search
Quickly finds pages or databases anywhere in your workspace by matching title keywords.

### update_page
Changes properties on an existing Notion page, such as marking it 'Done' or changing its owner.

## Prompt Examples

**Prompt:** 
```
Search my Notion workspace for 'Q3 Roadmap'.
```

**Response:** 
```
I found 2 pages mentioning 'Q3 Roadmap'. The primary document is at notion.so/q3-roadmap-xyz.
```

**Prompt:** 
```
List all items in database 'DATABASE_ID' marked as 'In Progress'.
```

**Response:** 
```
There are 4 tasks 'In Progress', including 'Redesign Header' and 'Optimize API calls'.
```

**Prompt:** 
```
Create a new note titled 'Meeting Notes' under page 'PAGE_ID'.
```

**Response:** 
```
Page 'Meeting Notes' created successfully.
```

## Capabilities

### Search the Knowledge Base
You can ask your agent to find pages or databases by title using the `search` tool.

### Run Database Reports
The `query_database` tool lets you filter and sort items in any Notion database with specific criteria.

### Read Full Page Content
Use `retrieve_page` to pull the complete content of a single Notion page by its ID.

### Edit Page Properties
You can change metadata—like status, owner, or date—on an existing page using `update_page`.

### Structure New Content
The agent uses `create_page` to build and save entirely new knowledge entries into your workspace.

## Use Cases

### The Q3 Status Report
A PM needs the status for 20 different features. Instead of opening 20 Notion pages, they tell their agent: 'List all items in the Product Backlog database where status is not Done.' The agent runs `query_database` and spits out a clean, aggregated list instantly.

### Updating Team Roles
An Ops Engineer notices several pages are outdated. They tell their agent to 'Update all project charter pages to reflect the new legal department owner.' The agent runs `update_page` against a group of IDs, saving hours of manual clicking.

### Deep Content Research
A writer needs context on a product feature. They use the agent to first run `search` for 'Feature X,' then select the top 3 results and ask the agent to `retrieve_page` from each one, compiling all three documents into their chat window.

### Onboarding New Users
A manager needs to onboard a new user. They tell the agent: 'Create a new page for Jane Doe under the HR Wiki.' The agent runs `create_page`, sets the title, and assigns initial template properties using schema knowledge.

## Benefits

- You can manage content structures instantly. Need to add a section or append notes? Use `append_block_children` instead of manually editing raw page code, keeping your workflow in chat.
- Data retrieval is surgical. Don't just read everything; use `query_database` to filter down exactly what you need—like 'all tasks assigned to Bob that are overdue.'
- Maintain a single source of truth. By connecting Notion through the agent, you treat your entire workspace as one massive, searchable knowledge base via the `search` tool.
- Work with structured data types. The `retrieve_database` tool lets you understand a database's schema before you write a query, which is key for reliable scripting.
- Build content on demand. Instead of making a draft page and forgetting it, use `create_page` to build out new documentation entries directly from your prompt.

## How It Works

The bottom line is: your AI client acts like a background worker, handling the API calls and data retrieval so you don't have to switch applications.

1. You tell your AI client what you need—for instance, 'Find all tasks for Q3 marked as high priority.'
2. The agent identifies the required data source and invokes `query_database`, passing in filters (e.g., status='High Priority' and date range='Q3').
3. The Notion MCP Server runs the query against your workspace, returning a structured list of results that the agent presents to you.

## Frequently Asked Questions

**How does the Notion MCP Server use `query_database`?**
It lets you query specific databases using filters, sorting criteria, and property names—all from your chat prompt. This is much more powerful than just browsing a view.

**Can I list all my workspaces with `list_databases`?**
No, `list_databases` only lists the databases *within* the single workspace that's connected to this integration instance.

**What does `retrieve_page` actually do?**
`retrieve_page` pulls all text and content from a specific page ID. It gives you the raw data structure, so your agent can read it immediately.

**How do I add new sections using `append_block_children`?**
You tell your agent which block or page to target, and what text/content to append. This keeps the writing process conversational.

**Is there a way to find pages by keyword? Use `search`.**
Yes, that's exactly what `search` does—it scans your workspace for titles or content matching keywords.

**When I use `list_users`, what data points can my agent collect about users?**
It provides a list of user IDs, names, and their associated email addresses. Your agent uses this to validate permissions or identify who owns a piece of content before making changes.

**How does `retrieve_block_children` handle deeply nested pages?**
It retrieves all immediate child blocks for a specified block ID. For deep nesting, your agent must call the tool sequentially on every returned child block until no further children are found.

**What information do I need to pass to `create_page`?**
You must provide the parent object and all required properties. The schema dictates what fields you need; if a property is mandatory but missing, the tool returns a specific validation error.

**Can the AI query specific rows in a Notion database?**
Yes! Supply the Database ID and you can filter rows by properties, check tags, and read text fields.

**Does it support creating new pages?**
Absolutely. The agent can construct a new page as a child of an existing page or database.

**How do I share my Notion pages with the integration?**
You must explicitly share specific databases or root pages with your 'Internal Integration' user via the Notion UI share menu.