Notion MCP Server
github.com/makenotion/notion-mcp-server- Category
- Developer Tools
- Rank
- No. 397Tools index
- Listed in
- #6 Connect tools with MCP
- Pricing
- Open Source
- Platform
- cli
- Type
- TOOL
- Builder
- makenotion
- GitHub
- 4.6k stars
- Latest release
- v2.1.0
- Added
- Jul 2, 2026
About
An official Model Context Protocol (MCP) server for the Notion API, enabling AI agents and tools like Claude and Cursor to read, create, and edit Notion pages and databases. It supports both a local npm/Docker setup and a newer remote OAuth-based server, with optimized Markdown-based page editing for token efficiency.
What it does
This TypeScript service turns operations from Notion’s OpenAPI description into agent-facing tools, then forwards requests to the underlying API. It builds input schemas automatically, manages endpoint-specific API headers, supports file uploads, and returns responses as MCP text content. Clients can connect through standard input and output or authenticated HTTP.
Why it's ranked here
The OpenAPI-driven design gives broad API coverage without hand-building every tool, while automatic discovery reduces client migration work. Markdown page operations cut context usage for reading and targeted editing. The main reservation is strategic: active support has moved to the hosted service, and this local repository may eventually be retired.
What's good
It handles several practical integration failures explicitly. Nested parameters accidentally serialized as JSON strings are normalized before forwarding. Read operations receive read-only hints, while writes receive destructive hints. HTTP mode requires bearer authentication unless an explicit unsafe option disables it. Per-operation API versions let newer Markdown endpoints coexist with the rest of the API.
Tradeoffs
Local setup still requires an integration token, selected workspace access, and careful capability scoping. Exposing workspace content to language models carries acknowledged data risk. The repository’s issues and pull requests are not actively monitored, and its local server may be sunset. Hardcoded prompts can also break when API migrations rename tools or replace database identifiers with data-source identifiers.
How to use it well
Choose it when an MCP client needs structured Notion automation through a locally controlled process or HTTP service. Grant only the pages and capabilities the workflow requires, preferably read-only access for retrieval tasks. Use Markdown operations for full-page reading or focused text replacement. It does not provide the supported hosted OAuth experience, and it intentionally excludes some dangerous API actions such as database deletion.
Technical notes+
src/init-server.ts loads the OpenAPI document and constructs MCPProxy. In src/openapi-mcp-server/openapi/parser.ts, OpenAPIToMCPConverter maps operations and schemas into MCP tool definitions, skips header parameters, handles references, and translates binary fields for local file paths. src/openapi-mcp-server/mcp/proxy.ts registers list and call handlers, truncates tool names to 64 characters, annotates GET operations as read-only, recursively unwraps structured JSON strings up to three times, and converts API failures into structured text responses. src/openapi-mcp-server/client/http-client.ts separates URL and body parameters, prepares multipart uploads, and applies OpenAPI header defaults per operation unless global headers override them. src/openapi-mcp-server/mcp/token.ts supports bounded token-shape checks, per-request token resolution, and redacted logging. scripts/build-cli.js bundles the TypeScript entry point into an executable Node 18 ESM CLI. vitest.config.ts configures Vitest, while package.json exposes build, development, test, watch, and coverage scripts.
Observed
- License
- MIT
- Primary language
- TypeScript
- Package
- Published as the npm package @notionhq/notion-mcp-server with an executable CLI
- Container installation
- Official Docker Hub image and local Docker Compose build are documented
- Interface
- MCP server with standard input/output and Streamable HTTP transports
- HTTP security
- Streamable HTTP requires bearer authentication unless explicitly disabled with an unsafe flag
- Runtime target
- The bundled executable targets Node.js 18
- Testing
- Vitest scripts cover normal runs, watch mode, and coverage
Read from README.md, package.json, src/init-server.ts, src/openapi-mcp-server/index.ts, src/openapi-mcp-server/mcp/proxy.ts, src/openapi-mcp-server/mcp/token.ts, src/openapi-mcp-server/auth/index.ts, src/openapi-mcp-server/auth/types.ts, src/openapi-mcp-server/auth/template.ts, src/openapi-mcp-server/openapi/parser.ts, src/openapi-mcp-server/client/http-client.ts, src/openapi-mcp-server/openapi/file-upload.ts, src/openapi-mcp-server/client/polyfill-headers.ts, vitest.config.ts, scripts/build-cli.js.
What it can do
Search Notion pages and databases by keyword
Search query string → List of matching Notion pages and databases with metadata
Create a new Notion page
Page title, content, and target parent page or database → Newly created Notion page with URL and ID
Edit existing Notion page content
Page ID and updated Markdown-formatted content → Updated Notion page with revised content blocks
Read Notion page content
Notion page ID or URL → Page content rendered as Markdown text
Query a Notion database
Database ID with optional filters and sort parameters → Filtered and sorted list of database entries
Create a new entry in a Notion database
Database ID and property values for the new row → Newly created database entry with assigned ID and properties
Update properties of a Notion database entry
Page/entry ID and new property values → Updated database entry reflecting the changed properties
Tags
Tech Stack
Comments (0)
No comments yet
Indexed by a proprietary survey. Corrections welcome.