Notion Link

Notion Link is an MCP server that provides the official Notion API integration for AI assistants, enabling full access to pages, databases, blocks, and workspace content within Notion. This MCP bridge allows language models to search, create, read, and update Notion pages and database entries through natural language commands, bringing conversational knowledge management to your Notion workspace.

When to Use This MCP Server

Connect this server when...

• Your team uses Notion for documentation, project management, or knowledge bases and you want AI-powered content access
• You need to create, update, and organize Notion pages and database entries through natural language commands
• You are building automated workflows that sync content between Notion and other platforms or data sources
• You want AI assistance searching across your Notion workspace to find specific information, documents, or database entries
• You need to generate reports or summaries from Notion database data for team meetings or stakeholder updates

Consider alternatives when...

• Your documentation and knowledge base lives in Confluence, Google Docs, or another platform with its own MCP server
• You only need to read publicly shared Notion pages without API-level access
• You require real-time collaborative editing features that go beyond the Notion API capabilities

Quick Start

Copy
# .mcp.json configuration
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_your_integration_token"
      }
    }
  }
}

Connection setup:

1. Go to notion.so/my-integrations and create a new integration
2. Copy the integration token (starts with ntn_)
3. Share the Notion pages or databases you want to access with the integration
4. Add the configuration above to your .mcp.json with your token
5. Restart your MCP client to connect to Notion

Example tool usage:

# Search for content
> Find all pages in the workspace that mention "quarterly review"

# Create a page
> Create a new page in the Engineering Wiki titled "API Authentication Guide"

# Query a database
> Show me all tasks in the Project Tracker database with status "In Progress"

Core Concepts

Concept	Purpose	Details
Pages	Content containers	Rich text documents with headings, paragraphs, lists, code blocks, and embedded content
Databases	Structured data	Collections of entries with typed properties (text, select, date, relation, formula)
Blocks	Content units	Individual content elements within pages (paragraphs, headings, to-dos, embeds, tables)
Integration Token	API access	Internal integration token that grants access to pages and databases shared with the integration
Sharing Model	Permission control	Notion pages must be explicitly shared with the integration to be accessible through the API

Architecture:

+------------------+       +------------------+       +------------------+
|  Notion          |       |  Notion MCP      |       |  AI Assistant    |
|  API             |<----->|  Server (npx)    |<----->|  (Claude, etc.)  |
|  api.notion.com  | HTTPS |  stdio transport  | stdio |                  |
+------------------+       +------------------+       +------------------+
        |
        v
+------------------------------------------------------+
|  Pages > Databases > Blocks > Properties > Search     |
+------------------------------------------------------+

Configuration

Parameter	Type	Default	Description
NOTION_TOKEN	string	(required)	Internal integration token from notion.so/my-integrations
default_database_id	string	none	Default database ID for query operations when not specified
page_size	integer	100	Number of results per page for database queries and search results
include_archived	boolean	false	Whether to include archived pages and database entries in results
rich_text_format	string	markdown	Format for text content in responses (markdown, plain, notion)

Best Practices

1. Share pages explicitly with the integration. The Notion API can only access pages and databases that have been explicitly shared with your integration. After creating the integration, navigate to each page or database you want accessible and share it via the three-dot menu. Parent page sharing propagates to child pages.

2. Use database queries with filters for efficient access. Notion databases can contain thousands of entries. Use property filters (status, date range, assignee) to narrow query results rather than fetching all entries and filtering client-side. This reduces API calls and response sizes.

3. Structure your workspace for API access. Organize your Notion workspace with a clear page hierarchy. Store related content under shared parent pages so you can grant access to entire sections by sharing the parent page. This simplifies integration management as your workspace grows.

4. Leverage database relations for connected data. When querying databases, include relation properties to understand how entries connect across databases. This allows the AI to follow relationships like project-to-task or team-to-member for comprehensive data retrieval.

5. Handle rich text content carefully. Notion blocks use a rich text format that supports mentions, equations, and inline code. When creating or updating content through the AI, ensure the text format is compatible with Notion's block structure to avoid formatting issues.

Common Issues

"Object not found" when querying a page or database. The page or database has not been shared with your integration. Navigate to the target page in Notion, click the three-dot menu, select "Connect to" and choose your integration. Sharing must be done explicitly for each top-level page.

Database query returns empty results despite existing entries. Check that the filter properties match the actual property names in the database (case-sensitive). Verify the property type matches the filter type. If filtering by select or status, ensure the option labels match exactly.

Integration token permissions too restrictive. When creating the integration, ensure you selected the appropriate capabilities (Read content, Update content, Insert content). If you need to create pages, the integration must have insert permission. Review capabilities at notion.so/my-integrations.