Log inSubmit server
Notion MCP Server logo

Notion MCP Server

by awkoy

Connects AI agents to Notion through three compact MCP tools for reading, writing, querying, and automating workspace content.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Notion MCP Server

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "awkoy-notion-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "notion-mcp-server"
      ],
      "env": {
        "NOTION_TOKEN": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— the server itself is confirmed live (we called its tools/list endpoint). The stdio install command is a separate, ongoing check.

Overview

awkoy/notion-mcp-server connects MCP-compatible clients to Notion with token authentication and three tools covering 43 operations. Agents can search and read pages, query databases, manage blocks, create or update content, add comments, handle files, and use templates. Batch writes support atomic behavior, idempotency keys, concurrency controls, and retry handling for rate limits. Reach for it when an agent needs unattended access in CI, cron jobs, background processes, or other headless environments.

Use cases

  • Search Notion pages and summarize matching project information
  • Query task databases using filters and identify overdue work
  • Create or revise pages from markdown
  • Rename many pages in one batched request
  • Run Notion maintenance jobs from CI or cron

Key features

  • Three MCP tools covering 43 Notion operations
  • Token authentication for headless and unattended use
  • Page, database, block, comment, file, and template operations
  • Batched writes with atomic rollback and idempotency keys
  • Markdown page input and output
  • Schema-guided errors and operation descriptions

Tools3

What Notion MCP Server lets your agent do. Expand a tool for its parameters.

Verified live~1.1k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

20/20 checks healthy over the last 78d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 9d ago via OSV.dev · notion-mcp-server (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars179Stargazers on the source repository.
npm downloads7.5kPackage downloads in the last 30 days.
Last commit1d agoMost recent push to the default branch.
Tools exposed3Callable tools this server registers over MCP.
Directory activity8 viewsConfig copies, upvotes, and views on AllMCPs.

How Notion MCP Server works

What awkoy/notion-mcp-server does

awkoy/notion-mcp-server exposes Notion operations through three MCP tools rather than a separate tool for each API action. The read tool handles searches, page retrieval, database queries, block traversal, and other non-mutating operations. The write tool covers changes such as creating pages, editing titles and properties, appending or updating blocks, adding comments, uploading files, applying templates, and removing content. A third tool describes an operation's JSON Schema and supplies an example request.

The server supports 43 operations across pages, databases, blocks, comments, files, and templates. Page content can be read as markdown, and several write operations accept markdown for creating or revising page content. Responses are reduced by default to limit context usage; a verbose flag returns the underlying Notion object.

How it works

Each read or write call includes an operation name and a payload containing that operation's fields. For example, a read request can use search_pages with a query, get_page with a page identifier, or query_database with a database identifier and optional filter. Write requests can be sent individually or as batches. Batch payloads can include multiple items, an atomic option, an idempotency key, and a concurrency limit.

Identifiers are flexible: fields such as page, block, database, and view IDs also accept copied Notion URLs. Block URL fragments can supply block identifiers, while the v query parameter in database links can supply view identifiers.

For complicated payloads—such as database filters, structured block trees, or database property definitions—notion_describe returns the expected schema and a usable example before execution. Simpler malformed requests return correction information with the error, allowing an agent to retry after one response.

Setup and configuration

The server uses the NOTION_TOKEN environment variable. It accepts either a Notion Personal Access Token or an internal integration secret. A Personal Access Token follows the user's Notion access, while an internal integration is limited to pages explicitly connected to that integration.

The package can be added to MCP clients with npx add-mcp notion-mcp-server --env NOTION_TOKEN=..., or configured manually with an mcpServers entry that runs npx -y notion-mcp-server. The documented clients include Claude Desktop, Claude Code, Cursor, VS Code, Codex, Gemini CLI, Cline, Windsurf, Zed, and Continue. Docker can run the image ghcr.io/awkoy/notion-mcp-server:latest with standard input enabled for stdio transport.

Claude Code also has a plugin installation path that stores the token in the system keychain and requires Node.js 22 or later. The plugin can provide a default parent page and a read-only mode.

Tools and capabilities

  • notion_read runs named read operations without modifying Notion.
  • notion_write runs named mutations, either singly or in batches.
  • notion_describe returns operation schemas, examples, and the tool to use.
  • Markdown input and output are available for supported page operations.
  • Batch writes support atomic rollback, idempotency keys, and configurable concurrency.
  • Slim responses reduce context use, with verbose: true available for raw objects.

Limitations and notes

Archive, trash, and delete operations remove content and should be confirmed with the user before execution. Notion access depends on the permissions represented by the configured token; an internal integration must be connected to each page it needs to access. Keep NOTION_TOKEN in the client or process environment, and do not omit it from generated MCP configuration.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Notion MCP Server

awkoy/notion-mcp-server is an MCP server that connects AI clients to Notion through token authentication and three tools: notion_read for non-mutating operations, notion_write for changes and batches, and notion_describe for schemas and examples. It supports pages, databases, blocks, comments, files, templates, and markdown content.

Install it with `npx add-mcp notion-mcp-server --env NOTION_TOKEN=...`, or add an MCP configuration that runs `npx -y notion-mcp-server`. The setup can configure clients such as Claude Desktop, Claude Code, Cursor, VS Code, Codex, Gemini CLI, Cline, Windsurf, Zed, and Continue.

The server requires `NOTION_TOKEN`. Set it to a Notion Personal Access Token or an internal integration secret. Personal Access Tokens follow the user's accessible workspace content, while internal integrations require explicit page connections.

Yes, awkoy/notion-mcp-server works with Cursor through an MCP configuration containing the server command and `NOTION_TOKEN`. The documented setup uses `npx -y notion-mcp-server`; the token can be entered in the generated Cursor entry.

Yes, `notion_write` accepts batch payloads with multiple items. Batch calls can use atomic behavior, idempotency keys, and configurable concurrency, which suits operations such as renaming many pages while reducing the number of agent tool calls.

Related MCP servers

All in Other Tools and Integrations All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewNotion MCP Server AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/awkoy-notion-mcp-server?style=directory)](https://allmcps.com/mcp/awkoy-notion-mcp-server)
HTML Embed
<a href="https://allmcps.com/mcp/awkoy-notion-mcp-server"><img src="https://allmcps.com/api/badge/awkoy-notion-mcp-server?style=directory" alt="Notion MCP Server on AllMCPs" /></a>