MCP Server

Knowledge ManagementNotion APIMIT

Notion MCP Server

Q: What is the Notion MCP Server?

Notion MCP Server is a Model Context Protocol integration that gives AI coding assistants direct access to Notion workspaces. It exposes page creation and editing, database querying and updating, block management, content searching, and property manipulation as MCP tools that Claude Code, Cursor, or any MCP-compatible client can call. This allows agents to read and write knowledge base content without leaving the IDE.

Q: How do I install and configure Notion MCP?

Install the server via npm and register it with your MCP client. You need a Notion internal integration token, which you create at notion.so/my-integrations. After creating the integration, share the specific pages or databases you want the agent to access with the integration. Set the NOTION_API_KEY environment variable to your integration token.

Q: Can Notion MCP create pages with rich formatting?

Yes. The server supports creating pages with headings, paragraphs, bulleted and numbered lists, code blocks, callouts, toggle blocks, tables, and inline formatting like bold, italic, and links. The agent constructs the block structure through the Notion API, producing properly formatted content that matches what you would create manually in the Notion editor.

Q: How does database querying work with Notion MCP?

The server exposes tools to query Notion databases with filters, sorts, and pagination. You can filter by any property type — text, number, date, select, multi-select, checkbox, and relation. The agent can construct complex compound filters with AND/OR logic, sort results by multiple properties, and paginate through large datasets automatically.

Q: Can Notion MCP update existing pages and properties?

Yes. The server provides tools to update page properties (title, status, dates, assignees, tags), append new blocks to existing pages, replace block content, and archive pages. The agent can modify database entries by updating their property values, making it useful for updating project statuses, adding notes, or maintaining changelogs.

Q: Is there a rate limit when using Notion MCP?

Notion enforces API rate limits of approximately 3 requests per second for internal integrations. The MCP server handles rate limiting automatically with retry logic and exponential backoff. For bulk operations like updating many database entries, the server batches requests to stay within limits while maintaining reliable throughput.

by Community · notion-mcp

Notion MCP Server gives your AI coding assistant direct access to your Notion workspace. Your agent can create richly formatted pages, query and update databases, manage block-level content, search across your entire workspace, and manipulate page properties — all through lightweight MCP tool calls without leaving your IDE. Your knowledge base becomes a living, agent-accessible resource.

Built on the official Notion API, this MCP server supports the full range of content operations. It handles page creation with complex block structures, database queries with filters and sorts, property updates across any data type, and full-text search with pagination. Whether you are maintaining project documentation, tracking tasks in a sprint board, or building a team knowledge base, the agent manages it conversationally while you stay focused on development.

14+

Tools Exposed

pages, databases, blocks, search...

<5min

Setup

npm install + integration token

Notion v1

API

official REST API

MIT

License

open source

Quick Install

claude mcp add notion -- npx notion-mcp-server

Key Features

Page Creation & Editing

Create pages with rich block content including headings, paragraphs, lists, code blocks, callouts, toggle blocks, and tables. Update existing page content by appending, replacing, or deleting blocks. Supports inline formatting with bold, italic, strikethrough, code, and hyperlinks.

Database Querying

Query Notion databases with powerful filtering across all property types — text contains, number ranges, date before/after, select equals, multi-select contains, and checkbox state. Combine filters with AND/OR logic, sort by multiple properties, and paginate through large result sets automatically.

Property Management

Read and update any page property type including title, rich text, number, select, multi-select, date, checkbox, URL, email, phone, relation, rollup, and formula. Batch-update multiple properties in a single API call for efficient database entry management.

Full-Text Search

Search across your entire Notion workspace by keyword with configurable filters for object type (page or database), last edited time, and parent location. Results include page titles, excerpts, and direct links for quick navigation to relevant content.

Block Management

Create, read, update, and delete individual blocks within pages. Support for nested blocks (children of toggle blocks, columns), block reordering, and type conversion. The agent can surgically modify specific sections without affecting the rest of the page.

Workspace Navigation

List all shared pages and databases, traverse the page hierarchy, and resolve page IDs from URLs. The agent can explore your workspace structure, find specific pages by title or path, and understand the organization of your knowledge base for context-aware operations.

Execution Brief

Use this page as a rollout checklist, not just reference text.

Suggest update

Tool Mapping Lens

Organize Tools by Workflow Phase

Catalog-oriented pages work best when users can map discovery, evaluation, and rollout in a clear path instead of reading an undifferentiated list.

Define the job-to-be-done first
Group tools by stage
Prioritize by adoption friction

Actionable Utility Module

Skill Implementation Board

Use this board for Notion MCP Server before rollout. Capture inputs, apply one decision rule, execute the checklist, and log outcome.

Input: Objective

Deliver one measurable improvement with notion mcp server claude code knowledge management workspace pages databases blocks

Input: Baseline Window

20-30 minutes

Input: Fallback Window

8-12 minutes

Decision Trigger	Action	Expected Output
Input: one workflow objective and release owner are defined	Run preview execution with fixed acceptance criteria.	Go or hold decision backed by repeatable evidence.
Input: output quality below baseline or retries increase	Limit scope, isolate root issue, and rerun controlled test.	One confirmed correction path before wider rollout.
Input: checks pass for two consecutive replay windows	Promote to broader traffic with fallback path active.	Stable rollout with low operational surprise.

Execution Steps

Record objective, owner, and stop condition.
Execute one controlled preview run.
Measure quality, latency, and correction burden.
Promote only when pass criteria are stable.

Output Template

tool=notion mcp server claude code knowledge management workspace pages databases blocks
objective=
preview_result=pass|fail
primary_metric=
next_step=rollout|patch|hold

Share execution feedback

What Is Notion MCP Server?

Notion MCP Server is a Model Context Protocol bridge that connects AI coding assistants to Notion workspaces through the official Notion API. It exposes page creation, database operations, block management, content search, and property manipulation as structured MCP tools that any compatible client can invoke directly from the IDE.

Developers and teams use Notion for project documentation, sprint planning, knowledge bases, and meeting notes. Notion MCP brings this content directly into the AI assistant workflow, eliminating the context switch between your code editor and the Notion web app. Ask "create a bug report page in the Sprint 14 database with priority High" and the agent creates the entry with all properties set correctly.

The server handles authentication through Notion internal integrations, which provide granular access control at the page and database level. You choose exactly which content the agent can access by sharing specific pages with the integration. This security model ensures the agent only reads and writes content you have explicitly authorized, preventing accidental access to sensitive team documents.

Notion MCP integrates naturally with other MCP servers in the ecosystem. Slack MCP can send notifications when pages are updated, Filesystem MCP can export content to local Markdown files, and Supabase MCP can sync database entries with application backends. Together, they create a connected knowledge management workflow orchestrated entirely by your AI assistant.

How to Calculate Better Results with notion mcp server claude code knowledge management workspace pages databases blocks

Create a Notion internal integration at notion.so/my-integrations. Give it a descriptive name like "Claude Code MCP" and select the workspace you want to connect. Copy the integration token — this is the API key the MCP server uses to authenticate. Keep this token secure and never commit it to version control.

Share the Notion pages and databases you want the agent to access with your integration. Open each page or database in Notion, click the three-dot menu, select "Add connections," and choose your integration. Only shared content is accessible through the API — unshared pages remain private even if the integration token is valid.

Install the MCP server via npm and register it with your AI client. For Claude Code, run the quick install command shown above with the NOTION_API_KEY environment variable set to your integration token. The server validates the token on startup and lists available pages to confirm the connection.

Verify the setup by asking your agent to search your Notion workspace for a known page title. If the agent returns the page with its properties and content preview, the connection is working. Try creating a test page and querying a database to confirm both read and write operations function correctly.

Treat this page as a decision map. Build a shortlist fast, then run a focused second pass for security, ownership, and operational fit.

When a team keeps one shared selection rubric, tool adoption speeds up because evaluators stop debating criteria every time a new option appears.

Worked Examples

Automated sprint retrospective documentation

Your team finishes a two-week sprint and needs to create a structured retrospective page with metrics, highlights, and action items pulled from the sprint database
Ask the agent to query the Sprint Tasks database via Notion MCP, filtering for tasks completed in the current sprint with their status, assignee, and story points
The agent calculates sprint metrics: total story points delivered, completion rate, average cycle time per task, and distribution across team members
A new retrospective page is created under the Retrospectives database with a formatted summary including a metrics table, completion chart description, and categorized task list
The agent queries the Blockers property across all sprint tasks to compile a "What Went Wrong" section, grouping blockers by category (technical debt, external dependencies, unclear requirements)
Action items from the retrospective discussion are added as a checklist block with assignees and due dates, and the page status is set to "Ready for Review" in the database

Outcome: A complete sprint retrospective document generated in minutes from live sprint data, with metrics, analysis, and action items — replacing an hour of manual compilation and formatting in Notion.

Developer onboarding knowledge base builder

A new developer is joining the team and you need to create a personalized onboarding page with relevant documentation links, setup instructions, and team contacts from across your Notion workspace
Ask the agent to search the Notion workspace for pages tagged with "onboarding," "setup guide," and "architecture" to compile a list of essential reading material
The agent creates a new onboarding page under the Team Hub with the new developer name and start date, structured with toggle sections for each onboarding phase (Day 1, Week 1, Month 1)
Each phase section is populated with linked references to existing documentation pages, inline instructions for environment setup, and callout blocks highlighting common gotchas the team has documented
The agent queries the Team Directory database to populate a "Key Contacts" section with names, roles, Slack handles, and areas of expertise relevant to the new developer role
A task checklist is appended with onboarding milestones (complete setup, first PR merged, shadow on-call, present to team) and the page is shared with the new developer through a Slack notification via Slack MCP

Outcome: A personalized onboarding page assembled from existing team knowledge in minutes, ensuring consistent onboarding quality and saving senior developers hours of manual documentation compilation.

Frequently Asked Questions

What is the Notion MCP Server?