# Notion MCP

> Notion MCP Server connects your AI client to the entire Notion workspace. It lets you query structured databases, search pages across titles and content, and read deep into nested document blocks—all through a single API layer. Don't copy-paste data or switch tabs; let your agent act as an intelligent librarian for all your wiki entries and project trackers.

## Overview
- **Category:** loved-by-devs
- **Price:** Free
- **Tags:** workspace-automation, database-query, document-management, fuzzy-search, block-management

## Description

Listen up. This MCP Server connects your AI agent to your entire Notion workspace, treating it like one massive, queryable database instead of a pile of documents you gotta copy-paste from.

Your agent handles everything: searching for info, reading deep into structure, or even dropping new records in. You don't have to jump between tabs or manually sift through pages; your AI client acts like an intelligent librarian who knows where every piece of data lives.

### Finding What You Need (Global Search & Discovery)

You can make your agent search the whole darn thing using fuzzy text matching. If you need a page, `search_pages` finds it across titles and content fragments everywhere in the workspace. Likewise, if you're looking for a specific database, `search_databases` performs that same global fuzzy search on every database title and its contents to pull out the right UUID.

### Reading and Understanding Content (Reading Tools)

When your agent needs information, it doesn't just read the surface. For deep dives, `get_blocks` reads the full, hierarchical block structure of any given page, letting you access nested text, lists, and content down to the deepest level.

If all you need is basic info—say, checking what a single page is about without reading its whole body—you use `get_page`, which pulls only the metadata properties like title or status. Need to know how a database is set up? `get_database` retrieves the schema definition for any Notion database, telling you exactly what column headers and data types it uses.

### Querying and Managing Data (Structured Interaction)

When your job involves structured data, this is where the server shines. You use `query_database` to extract specific rows of information from a database, running defined filters or queries so you get exactly what you need—no extra junk.

If the data's wrong or needs updating, your agent can fix it. It uses `create_page` to drop an entirely new record or page into an existing Notion database structure. You can also insert a specific data row directly into one of those databases. If a title changes but you don't want to rebuild the content, `update_page_title` handles that for you.

### Administration and Maintenance (Cleanup & Users)

When the job is done or something needs clearing out, your agent can use `archive_page` to delete or archive a specified Notion page. To keep track of who's doing what, `list_users` pulls a list of every active user and bot integration connected within the workspace domain.

## Tools

### append_block_children
) to the end of a page or nested block. Provide blocks as a JSON array of Notion block objects. Example for a paragraph: [{"type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"Hello world"}}]}}]

Append content blocks to a Notion page or block

### archive_page
Deletes or archives a specified Notion page.

### create_database
Properties define columns. Minimum: provide a title property with type "title".

Create a new Notion database inside a page

### create_page
Inserts a new record (row or page) into an existing Notion database.

### delete_block
) from a page. This action is irreversible — the block and all nested children are permanently deleted.

Permanently delete a Notion block

### get_blocks
Reads the full, hierarchical textual content contained within a specific Notion page.

### get_database
Retrieves the schema definition—the column headers and types—of a specified Notion database.

### get_page
Reads only the metadata properties (title, status) of a single Notion page, not its body text.

### list_users
Lists all active users and bot integrations within the connected workspace.

### query_database
Extracts structured data rows from a Notion database based on filters or queries.

### search_databases
Performs a global fuzzy search across the titles and content of all databases in the workspace to find their UUIDs.

### search_pages
Performs a global fuzzy search across every page in the workspace, finding pages by title or keyword.

### update_page_properties
) using the Notion properties schema. Provide the properties as a JSON object matching the Notion API property format.

Update arbitrary properties on a Notion page

### update_page_title
Changes the visible title of an existing Notion page.

## Prompt Examples

**Prompt:** 
```
Search my Notion workspace for any pages containing 'Q4 Marketing Strategy'.
```

**Response:** 
```
I searched your Notion workspace and found the page 'Q4 Marketing Strategy (Final)' with ID `abc-123`. Let me know if you would like me to read the contents of its blocks.
```

**Prompt:** 
```
Create a new row in my Project Tasks database marking the title as 'Update API Docs'.
```

**Response:** 
```
I've successfully created a new active row 'Update API Docs' within the Project Tasks database. The new record has been initialized and is ready for further updates.
```

**Prompt:** 
```
List all team members currently registered in my Notion.
```

**Response:** 
```
Here are the users active within your Notion domain: Jane Doe (`jane@domain.com`), John Smith (`john@domain.com`), and 3 active Bot integrations.
```

## Capabilities

### Query Structured Data
Reads specific data rows from a Notion database using defined filters.

### Search Content Globally
Uses fuzzy text matching to locate pages or databases across the entire workspace by title or content fragment.

### Read Document Structure
Dives into a page's internal block hierarchy, reading metadata and nested textual content for summarization.

### Manage Records
Creates new pages or inserts data rows directly into existing Notion databases.

### Map Users
Lists all active users and bot accounts within the connected Notion workspace domain.

## Use Cases

### Finding a forgotten document
A Product Manager needs the original spec for 'Project Phoenix.' Instead of searching keywords and getting 50 results, they ask their agent. The agent uses `search_pages` to pinpoint the exact page UUID, giving them immediate access.

### Generating a status report
An Ops Manager needs to know which tasks are overdue across three different departmental trackers. They use `query_database` repeatedly for each tracker and ask the agent to compile one unified summary of only 'Status: Blocked' records.

### Updating a central resource guide
A Developer writes new API documentation. Instead of manually updating the main database, they use `create_page` within the centralized 'API Docs' database to insert a brand-new, correctly formatted record.

### Summarizing meeting outcomes
A Knowledge Worker has 10 pages worth of raw meeting notes. They pass the page UUIDs to their agent, which calls `get_blocks` on each one, and summarizes all key decisions into a single bulleted list.

## Benefits

- **Find anything instantly:** Use `search_pages` to skip the manual wiki crawl. You can find specific documentation fragments or misplaced meeting notes using natural language queries.
- **Structure your data flow:** Forget reading scattered text. Running `query_database` gives you clean, tabular data rows that your agent processes directly—perfect for reporting.
- **Know who's involved:** The `list_users` tool provides a real-time roster of team members and active bots, eliminating guesswork when assigning tasks.
- **Maintain data integrity:** Instead of manually editing fields, use `create_page` or `update_page_title` to programmatically manage records inside the database structure.
- **Read context deeply:** `get_blocks` reads beyond just the title. It accesses nested lists and paragraphs, allowing your agent to summarize complex project specs accurately.

## How It Works

The bottom line is: you send a natural language request, and the agent runs multiple specific Notion API calls to build the answer.

1. Subscribe to this server, then input your Notion Internal Integration Secret into your AI client.
2. Your agent initiates a command (e.g., 'What was the Q4 marketing budget?').
3. The server executes the necessary tools (`query_database` or `search_pages`) and returns structured data for your AI client to interpret.

## Frequently Asked Questions

**How do I find a database ID using the Notion MCP Server?**
You use `search_databases`. This tool runs a fuzzy search across all databases in your workspace, returning the UUIDs necessary to reference them later for querying.

**Can I read content from a whole database using query_database?**
Yes. The `query_database` tool lets you filter and extract specific rows of structured data based on criteria, giving you clean output instead of just the schema definition.

**Does Notion MCP Server let me read a page's entire text?**
Yes. Use `get_blocks`. This function reads the full block hierarchy—meaning it accesses nested paragraphs, lists, and images, not just the title or basic metadata.

**How do I list all team members in Notion?**
You run the `list_users` tool. It enumerates every active user account and bot integration currently registered within your workspace domain.

**How does the `create_page` tool insert data into a database?**
It initializes new rows or pages inside any specified Notion container. You provide the necessary title and property values, making the record immediately active in your workspace.

**What information does `get_page` retrieve about a Notion Page?**
This tool retrieves only the page's metadata properties, not its body text. This is faster than reading content and gives you details like the title, parent ID, or last modified date.

**How does `search_pages` help me find document IDs?**
It performs a fuzzy text search across all pages in your entire workspace. You use this tool when you only know keywords and need the Page UUID to interact with other tools.

**Can I use `archive_page` to clean up old documents?**
Yes, this tool handles the archiving or soft deletion of a Notion page. You must provide the specific Page ID you intend to remove from active view in your system.

**Can my AI automatically create task assignments?**
Yes. Your agent can pull the exact schema of your tracker database, retrieve the user UUIDs via `list_users`, and seamlessly insert a new row assigning the task—all within seconds.

**How do I extract long notes from a page?**
While `get_page` gives you raw page metadata, your agent will use `get_blocks` to traverse paragraphs, lists, and images to stream the entire document context back into your chat workflow.

**Does it support deep searches?**
Absolutely. It leverages multiple endpoints like `search_pages` and `search_databases` globally so your agent can track down any missing document UUID using just a textual query snippet.