Notion
Turn your Notion workspace into a queryable knowledge base for AI agents
The official Notion MCP server, maintained by Notion, lets AI agents read pages, query databases, create content, and search across your workspace through the Model Context Protocol. Version 2.x exposes 22 tools built on Notion's data sources API, with optimized token consumption for agent use.
If your team lives in Notion, every important decision, spec, project brief, and meeting note probably ends up there. The problem, until recently, was that an AI agent couldn't actually read any of it. You could paste excerpts into a chat, but the agent had no persistent, queryable access to your workspace. The Notion MCP server changes that. Once it's wired in, an agent running inside Claude or any other MCP client can search your workspace, pull up specific pages, query a database of open projects, and write back to Notion, all as part of a conversation.
This review covers what the server actually does, how to set it up, where it works well, and where you'll run into friction.
What the Notion MCP server is
Notion released this officially in 2025 under the MIT license. The GitHub repo lives at makenotion/notion-mcp-server and as of version 2.1.0 (January 2026) it's on 4.3k stars. The server is written in TypeScript and published to npm as @notionhq/notion-mcp-server.
Version 2.0 was a breaking change from 1.x. The older version hit the Notion API directly with standard REST endpoints. The new version is built on Notion's data sources API, which gives it richer structured access to database properties and was designed with token efficiency in mind. If you're upgrading from a 1.x setup, the tool names and output formats changed, so your prompts will need updating.
Notion runs a remote version of the server as well. It uses OAuth, which is simpler to configure in most hosted clients. The local npm package is useful if you want to self-host or if your MCP client doesn't support remote servers, but Notion's docs now recommend the remote path and acknowledge the local package may sunset eventually.
What it can actually do
The server exposes 22 tools. The ones you'll reach for most are:
Reading content. You can fetch a specific page by ID, retrieve its child blocks (the actual content), and read database properties. Pages come back in Markdown, which is readable for both agents and humans and keeps token counts reasonable.
Search. There's a workspace search tool that queries across all pages and databases the integration has been shared with. Search in Notion is fuzzy and fast, and the MCP tool surfaces the same results you'd see from the search bar in the app. The catch, which matters for agent workflows, is that results are limited to content shared with your integration. If a page wasn't explicitly connected, the agent can't see it.
Database queries. This is where the server earns its place in serious workflows. You can filter a database by property values, sort results, and page through entries. A project tracker database, a CRM table, a content calendar, a bug list - any of these become queryable knowledge bases once you share them with the integration. An agent can ask "show me all open Q3 projects assigned to the marketing team" and get structured results back without any manual data export.
Creating and updating content. The server can create new pages inside a specified parent page or database, update existing page content, and add comments. Write operations work well for straightforward content, though the block structure Notion uses internally means complex formatting sometimes comes out slightly different from what you'd expect when building it by hand.
Setup: the friction points
Installation is one command: npx -y @notionhq/notion-mcp-server. The config for Claude Desktop or Claude Code looks like this:
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"NOTION_TOKEN": "your_integration_token_here"
}
}
}
}The part most people miss on first setup: you have to explicitly share pages and databases with your integration inside Notion. The integration doesn't get blanket access to your workspace. You go to each page or database, open the connections menu, and add your integration. For a team workspace with content scattered across dozens of sections, this can be tedious. The practical approach is to create a dedicated parent page that acts as the integration's "view" of your workspace and share that. Child pages inherit the sharing.
If you're using the remote server path with OAuth, the flow is simpler: you authenticate once and choose which pages to allow during the OAuth consent screen. The token rotation is handled automatically.
Rate limits and what they mean in practice
Notion's API caps requests at an average of three per second per connection. For a conversational workflow where a user asks one question and the agent makes a handful of API calls to answer it, this is invisible. For an agent running a batch job, say, syncing 500 database entries or scraping a large page hierarchy, it matters a lot.
A heavy agent workflow that kicks off 20 or 30 API calls in quick succession will start hitting 429 responses. The server surfaces these as errors, and your MCP client will need to handle retry logic. Well-behaved agents back off using the Retry-After header that Notion sends with each 429. Not all MCP clients implement this gracefully out of the box.
The practical implication: the Notion MCP server is a good fit for interactive, on-demand queries. It's a less natural fit for long-running batch operations without some throttling layer in front of it. If you're running Claude Code as your agent and asking it to work through a hundred Notion pages, plan for it to take longer than you'd expect.
The read-vs-write tradeoff
The server's read capabilities are where most of the day-to-day value comes from. An agent that can search your Notion workspace and pull up relevant context doesn't need you to remember exactly which page has the right spec. You ask, it finds, it reads.
Write capabilities are genuinely useful but worth approaching with some caution. There's no undo mechanism in the MCP layer. If an agent creates a page with the wrong content or updates something it shouldn't have, you're fixing it manually. The better pattern is to use the agent for drafting: have it create a new page with proposed content and then review it yourself before treating it as canonical. That's a reasonable workflow for things like auto-generating meeting notes from a transcript or creating a first draft of a project brief.
For teams using Notion as a wiki or single source of truth, write operations probably belong behind a human-in-the-loop approval step. The agent proposes, you approve, the write happens. Automation without any review step is fine for lower-stakes content like personal notes or draft scratch pads.
Who this is most useful for
The clearest beneficiaries are teams where Notion is already the primary knowledge store. If your product specs, project plans, OKRs, and customer research all live in Notion, giving your AI agent access to that context immediately makes every agent interaction more grounded. Instead of the agent working from whatever you happen to paste into the chat, it can look things up in context.
Notion AI, Notion's own AI product, operates natively inside the app and has broader page access by default. The MCP server serves a different use case: it brings your Notion data into an external agent, which could be Claude, a custom agentic workflow, or any other MCP client. If you want Claude to reference your Notion workspace while helping you write code or plan a project, that's the MCP server's job.
The server is also a reasonable choice for solo knowledge workers who use Notion as a personal operating system. An agent that can search your notes, surface relevant past writing, and add to your database without you having to switch apps closes a loop that used to require manual copy-paste.
What it doesn't do
A few things worth knowing before you build around this server:
The server doesn't give you real-time sync or webhooks. It's a pull-based tool: the agent asks for data when it needs it. If you want an agent that reacts to Notion changes automatically, you need the Notion API directly with webhook support, which is outside the MCP server's scope.
Page permissions aren't granular at the tool level. The integration gets access to whatever you've shared with it, and the agent gets all of that. You can't tell the agent "you can read the project tracker but not the HR database" without creating separate integrations with different sharing scopes.
Complex Notion blocks, like synced blocks, embedded databases inside pages, or certain toggle structures, sometimes come back in simplified form that loses hierarchy. For most reading tasks this doesn't matter, but for workflows that need to reproduce the exact page structure, test it first.
Getting started quickly
The fastest path to a working setup:
- Go to notion.so/profile/integrations and create a new internal integration. Give it a descriptive name and keep it internal for now.
- Copy the integration token.
- Inside Notion, share a test database or page with that integration using the connections menu on the page.
- Add the server to your MCP client config with the token as shown above.
- Restart your client, then ask the agent to search for something you know exists in that shared page.
Once that search returns real results, the integration is working. From there you can expand which pages are shared and start building out more specific workflows.
For building more complex agent pipelines that call multiple MCP servers together, the MCP server directory has a growing list of servers that pair well with Notion: document servers for local file access, browser servers for pulling in external content, and so on.
The bottom line
The Notion MCP server is one of the more immediately useful integrations in the MCP ecosystem because Notion is where a lot of team knowledge already lives. The read side works reliably: searching the workspace, querying databases, and fetching page content all perform as expected. The write side works too, but it's worth treating agent writes as drafts that a human reviews rather than final operations.
Rate limits at three requests per second mean this isn't a batch processing tool. It's an interactive, on-demand knowledge layer for agents that need context from your workspace. For that use case, it does exactly what it promises, and the setup from zero to working is under ten minutes if you've done MCP configuration before.
If you're building an AI coding or research workflow with Claude and your context lives in Notion, wiring this up is one of the higher-return MCP integrations available. Compare it with similar productivity integrations in the best AI agent for coding guide to see where it fits in a broader toolchain.
Features
- Read, create, and update Notion pages
- Query and filter database entries
- Full-text search across the workspace
- Comment reading and creation
- Markdown-based page editing
- 22 tools built on the data sources API
- STDIO and Streamable HTTP transport
How to set up the Notion MCP server
- Create a Notion internal integration at notion.so/profile/integrations and copy the token
- Share the pages or databases you want the agent to access with that integration
- Add the server to your MCP client config using npx -y @notionhq/notion-mcp-server
- Set NOTION_TOKEN in your environment or pass it via the config
- Restart your MCP client and the Notion tools appear