Notion MCP Server
MCP ServerFreeSearch, read, and edit Notion pages and databases via MCP.
Capabilities14 decomposed
openapi-driven dynamic tool generation from notion api specification
Medium confidenceAutomatically generates MCP tool definitions at server startup by parsing the Notion OpenAPI specification (notion-openapi.json), eliminating manual tool definition and ensuring 100% API surface coverage. The MCPProxy class reads the OpenAPI schema, converts each operation into an MCP tool with proper parameter schemas and descriptions, and registers them in the tool registry for client discovery. This approach keeps tools synchronized with Notion API updates without code changes.
Uses declarative OpenAPI-to-MCP conversion at startup rather than hardcoded tool definitions, enabling zero-maintenance API surface exposure. The MCPProxy translates OpenAPI operations directly to MCP tool schemas with parameter validation, avoiding the need for manual tool registration code.
Faster to maintain than hand-coded tool definitions and automatically covers new Notion API endpoints without code changes, unlike static MCP server implementations that require manual updates for each API operation.
dual transport protocol support (stdio and http) with automatic client negotiation
Medium confidenceImplements both STDIO (for desktop AI clients like Claude Desktop, Cursor, Zed) and HTTP (for web-based applications) transport layers through MCP SDK abstractions, allowing a single server binary to serve different client types. The transport layer is selected at startup via CLI arguments and environment configuration, with the server automatically handling protocol-specific serialization, framing, and error handling. This enables deployment flexibility without maintaining separate server implementations.
Abstracts transport differences through MCP SDK's transport layer, allowing a single codebase to serve STDIO and HTTP clients without conditional logic in the core MCPProxy. The transport is injected at initialization, making the protocol bridge transport-agnostic.
More flexible than single-transport MCP servers (e.g., STDIO-only implementations) because it supports both desktop and web clients from one deployment, and more maintainable than separate server implementations because transport logic is centralized in the SDK.
notion database property schema introspection and type discovery
Medium confidenceRetrieves the schema of a Notion database, including all properties (columns), their types (text, select, date, relation, etc.), and configuration (options for select properties, relation targets, etc.). This capability enables AI clients to discover what properties exist in a database and their constraints before querying or updating rows. The introspection tool fetches the database object from the Notion API and extracts the properties schema.
Exposes Notion's database schema through MCP tool interface, allowing AI agents to dynamically discover property types and constraints without hardcoding schema knowledge. This enables adaptive database interactions.
More flexible than hardcoded schema because it adapts to database changes, but requires additional API calls and adds latency compared to pre-configured schema knowledge.
notion page property updating with type-aware value conversion
Medium confidenceUpdates specific properties of a Notion page (when the page is part of a database) with type-aware value conversion, handling different property types (text, select, date, relation, checkbox, etc.) and converting input values to Notion's internal format. The update page properties tool accepts a page ID and a properties object, validates values against the property schema, converts them to Notion format, and sends a PATCH request. This enables AI agents to update database rows without needing to know Notion's internal property value representation.
Implements type-aware property value conversion, translating user-friendly values (e.g., 'Done', '2025-01-15') to Notion's internal property format (select IDs, ISO dates) without requiring clients to know the conversion rules. The implementation validates values against the database schema.
More user-friendly than raw Notion API calls because it handles type conversion automatically, but requires schema knowledge to validate values and may not support all complex property types that the raw API supports.
notion page deletion with cascade handling for nested content
Medium confidenceDeletes a Notion page and optionally its nested content (child blocks, database rows) through the Notion API. The delete page tool accepts a page ID and an optional cascade flag, constructs a DELETE request, and removes the page from the workspace. This enables AI agents to clean up pages or remove outdated content programmatically.
Exposes Notion's page deletion API through MCP tool interface, allowing AI agents to remove pages programmatically. The implementation handles the permanent nature of deletion and provides clear feedback.
Simpler than manual deletion through the Notion UI, but more dangerous because deletion is permanent and cannot be undone through the API, unlike the UI which provides a trash/recovery mechanism.
mcp server startup and configuration with cli argument parsing
Medium confidenceInitializes the MCP server by parsing command-line arguments (transport type, port, API token), loading the OpenAPI specification, initializing the MCPProxy with converted tool definitions, creating the appropriate transport layer (STDIO or HTTP), and starting the server. The startup process is orchestrated by the CLI binary (bin/cli.mjs) which delegates to scripts/start-server.ts. This capability handles all initialization logic needed to bring the server from startup to ready-to-accept-connections state.
Orchestrates multi-step initialization (OpenAPI loading, MCPProxy creation, transport setup) through a single CLI entry point, with configuration driven by command-line arguments and environment variables. The startup process is designed for containerized deployment.
Simpler to deploy than servers requiring complex configuration files because it uses CLI arguments and environment variables, but less flexible than servers supporting configuration files or dynamic reconfiguration.
stateless request-response handling with environment-based authentication
Medium confidenceEach MCP tool invocation is independently stateless, with authentication credentials (Notion API token) managed via environment variables rather than session state or connection-level auth. When a client calls a tool, the HttpClient retrieves the API key from the environment, constructs the HTTP request with proper headers, executes it against the Notion API, and returns the response without maintaining any inter-request state. This design simplifies deployment and scaling but requires the API token to be available in every server instance's environment.
Implements strict statelessness where each tool call is independent and authenticated via environment variables, avoiding session management complexity. The HttpClient is instantiated fresh per request with credentials from the environment, making the server horizontally scalable without shared state.
Simpler to deploy than stateful MCP servers that maintain connection pools or session caches, and more suitable for serverless/containerized environments, but less flexible than servers supporting per-user authentication or token refresh mechanisms.
protocol translation between mcp tool abstraction and notion rest api operations
Medium confidenceThe MCPProxy class translates between MCP's tool-based abstraction (listTools, callTool methods) and Notion's REST API operations by mapping MCP tool parameters to HTTP request components (URL, method, headers, body). When a client calls an MCP tool, MCPProxy converts the tool name and parameters into an HTTP request using the OpenAPI schema, executes it via HttpClient, and converts the HTTP response back into MCP tool result format. This translation layer abstracts away HTTP details from the MCP client.
Implements bidirectional protocol translation in MCPProxy where MCP tool calls are converted to HTTP requests using OpenAPI schema as the mapping source, and HTTP responses are converted back to MCP results. This eliminates the need for manual request/response handling code.
More maintainable than hardcoded HTTP client code because the translation logic is driven by OpenAPI schema, and more flexible than direct REST API clients because it abstracts HTTP details behind the MCP tool interface.
notion workspace page search and retrieval with full-text indexing
Medium confidenceEnables AI clients to search across all pages in a Notion workspace using the Notion API's search endpoint, returning matching pages with metadata (title, ID, URL, last edited time). The search capability translates MCP tool parameters (query string, filter options) into Notion API search requests, supporting full-text search across page titles and content. Results are returned as structured JSON with page identifiers that can be used for subsequent read/update operations.
Exposes Notion's native search API through MCP tool interface, allowing AI clients to discover pages without requiring manual page ID knowledge. Search results include page metadata needed for subsequent operations (read, update).
More efficient than iterating through all pages to find matches because it uses Notion's server-side search, but less powerful than full-text search solutions because it only searches page titles and metadata, not content.
notion page content block reading with hierarchical structure preservation
Medium confidenceRetrieves the full content of a Notion page as a hierarchical structure of blocks (paragraphs, headings, lists, code blocks, etc.), preserving nesting relationships and formatting metadata. When a client calls the read page tool with a page ID, the HttpClient fetches the page's block children from the Notion API, recursively retrieves nested blocks, and returns a structured representation that maintains parent-child relationships. This enables AI clients to understand page structure and content without flattening the hierarchy.
Recursively fetches and preserves Notion's hierarchical block structure, maintaining parent-child relationships that are essential for understanding page layout. The implementation handles nested blocks by making recursive API calls and reconstructing the hierarchy client-side.
More complete than simple page content retrieval because it preserves block nesting and structure, but requires more API calls than flat content extraction and adds latency for deeply nested pages.
notion page content block creation and insertion with position control
Medium confidenceCreates new content blocks within a Notion page at specified positions (after a specific block, at the end of the page, or within nested structures). The create block tool accepts a page ID, block type (paragraph, heading, list item, code block, etc.), content, and optional position parameters, then constructs a Notion API request to insert the block. This enables AI agents to add content to pages programmatically while controlling where new blocks appear in the hierarchy.
Supports position-controlled block insertion through the Notion API's 'after' parameter, allowing AI agents to insert blocks at specific locations rather than only appending to the end. This enables more sophisticated content generation workflows.
More flexible than simple append operations because it supports position control, but less powerful than batch operations because each block requires a separate API call, making bulk content creation slower than direct API usage.
notion page content block updating with selective field modification
Medium confidenceUpdates existing content blocks within a Notion page by modifying specific fields (text content, formatting, type) without replacing the entire block. The update block tool accepts a block ID and a set of field updates, constructs a Notion API PATCH request, and applies only the specified changes. This enables AI agents to edit page content incrementally (e.g., fixing typos, adding formatting) without losing other block metadata or structure.
Implements selective field updates through Notion's PATCH API, allowing AI agents to modify specific block properties without replacing the entire block. This preserves block metadata and relationships while enabling targeted edits.
More efficient than delete-and-recreate workflows because it preserves block identity and metadata, but less flexible than full block replacement because it cannot change block types or perform complex structural transformations.
notion page creation with database and property configuration
Medium confidenceCreates new pages in a Notion workspace with optional database configuration, setting initial properties (title, icon, cover image) and database schema (columns, property types). The create page tool accepts a parent (workspace or database), page title, and optional properties object, constructs a Notion API request, and returns the created page ID and metadata. This enables AI agents to create new pages and configure them with initial structure without manual Notion UI interaction.
Supports creating pages with initial properties configured through the Notion API, allowing AI agents to set up pages with database fields and metadata at creation time. This reduces the number of API calls needed to fully configure a new page.
More complete than simple page creation because it supports property configuration, but less flexible than manual Notion UI because it cannot apply templates or complex initial structures that require multiple API calls.
notion database querying with filtering, sorting, and pagination
Medium confidenceQueries Notion databases to retrieve rows (pages) matching specified criteria, with support for filtering (by property values), sorting (by property, ascending/descending), and pagination (limit, offset). The query database tool accepts a database ID and optional filter/sort parameters, constructs a Notion API query request, and returns matching pages with their property values. This enables AI agents to search and retrieve structured data from Notion databases without iterating through all pages.
Translates MCP tool parameters into Notion's filter and sort API format, supporting database queries with filtering, sorting, and pagination through a single tool call. The implementation handles parameter validation and conversion to Notion's filter syntax.
More efficient than retrieving all database pages and filtering client-side because it uses server-side filtering, but less powerful than SQL-like query languages because it supports only simple filters and single-property sorting.
Capabilities are decomposed by AI analysis. Each maps to specific user intents and improves with match feedback.
Related Artifactssharing capabilities
Artifacts that share capabilities with Notion MCP Server, ranked by overlap. Discovered automatically through the match graph.
notion-mcp-server
Official Notion MCP Server
notion-agent
Agent-native CLI + MCP server for the Notion API — wraps every Notion endpoint as a CLI command and MCP tool
Notion
** - Integrates with Notion's API to manage personal todo list
GPTScript
Natural language scripting framework.
WorkGPT
GPT agent framework for invoking APIs
anytype-mcp
An MCP server enabling AI assistants to interact with Anytype - your encrypted, local and collaborative wiki - to organize objects, lists, and more through natural language.
Best For
- ✓MCP server developers building integrations with large REST APIs
- ✓Teams maintaining long-lived API bridges that need to track upstream API changes
- ✓Builders who want to avoid manual tool definition maintenance
- ✓Developers building MCP servers that need to support multiple client types
- ✓Teams deploying to heterogeneous environments (desktop + web + CLI)
- ✓Organizations wanting a single deployment artifact for multiple use cases
- ✓AI agents that need to understand database structure before querying or updating
- ✓Builders implementing dynamic database interactions without hardcoded schema knowledge
Known Limitations
- ⚠Requires a valid OpenAPI specification file (notion-openapi.json) to be present at startup — missing or malformed spec will fail server initialization
- ⚠OpenAPI-to-MCP conversion may lose fidelity for complex API patterns not well-represented in OpenAPI (e.g., streaming, webhooks, conditional parameters)
- ⚠Tool discovery latency scales with OpenAPI spec size — large specs may add 100-500ms to server startup
- ⚠STDIO transport is blocking and single-connection — cannot handle concurrent clients; suitable only for single-client desktop scenarios
- ⚠HTTP transport requires explicit port configuration and network exposure — adds security considerations (CORS, authentication) not present in STDIO
- ⚠Transport selection is made at startup — cannot dynamically switch transports without server restart
Requirements
Input / Output
UnfragileRank
UnfragileRank is computed from adoption signals, documentation quality, ecosystem connectivity, match graph feedback, and freshness. No artifact can pay for a higher rank.
About
MCP server for Notion workspace integration. Enables searching pages, reading and updating content blocks, creating new pages, querying databases, and managing properties in Notion workspaces.
Categories
Alternatives to Notion MCP Server
Are you the builder of Notion MCP Server?
Claim this artifact to get a verified badge, access match analytics, see which intents users search for, and manage your listing.
Get the weekly brief
New tools, rising stars, and what's actually worth your time. No spam.
Data Sources
Looking for something else?
Search →