@mcp-monorepo/notion-query

MCP server for querying Notion data sources.

The Notion Query MCP server provides a comprehensive suite of tools for interacting with a Notion workspace. It enables AI models to read, search, create, and update Notion pages and databases programmatically.

At its core, the package features a powerful local synchronization and search system. It continuously downloads content from the Notion workspace, converts it to a clean Markdown format, and indexes it in a local Retrieval-Augmented Generation (RAG) vector store. This architecture allows for incredibly fast and accurate semantic search across all your Notion documents.

Key Features

• Comprehensive Notion Integration: Provides a full set of tools to create, fetch, query, update, and search for content within Notion.
• Local RAG-based Search: Utilizes a local vector store for fast, offline-capable semantic search across the entire workspace, independent of Notion's own search capabilities.
• Robust Synchronization: A throttled, queue-based background process keeps the local content cache up-to-date with changes in Notion, ensuring search results are fresh.
• Rich Markdown Conversion: Converts Notion's complex block structure into a clean, model-friendly Markdown format, preserving formatting like headings, lists, and colors.
• Database and Page Manipulation: Supports advanced operations such as querying database views with filters and sorts, creating new pages with structured properties, and performing granular content updates.
• Dynamic Discovery: Automatically discovers and indexes new pages linked within existing synchronized content.

Windows Setup Requirement

The Local RAG-based Search feature relies on the @huggingface/transformers library, which uses native code (ONNX Runtime) for high-performance machine learning operations.

To ensure this works correctly on Windows, users must install the Microsoft Visual C++ Redistributable. Failure to do so will result in a DLL initialization routine failed error when the application starts.

• Download Link: Latest supported Visual C++ Redistributable downloads
• File to Install: Under the "Visual Studio 2015, 2017, 2019, and 2022" section, download and run vc_redist.x64.exe.
• A system restart is recommended after installation.

Usage

You can run this MCP server directly using npx for local testing:

npx @mcp-monorepo/notion-query@latest

To integrate this server with a compatible AI model (like Claude), provide the following MCP server configuration:

{
  "mcpServers": {
    "notion-query": {
      "command": "npx",
      "args": [
        "-y",
        "@mcp-monorepo/notion-query"
      ],
      "env": {
        "NOTION_API_KEY": "<Your NOTION_API_KEY Here>",
        "NOTION_QUERY_APP_DATA_DIR": "<Your NOTION_QUERY_APP_DATA_DIR Here>",
        "NOTION_SYNC_BATCH_SIZE": "30",
        "NOTION_SYNC_INTERVAL_MS": "900000",
        "NOTION_GC_INTERVAL_MS": "21600000"
      }
    }
  }
}

Environment Variables

| Variable | Description | Default | | :--- | :--- | :--- | | NOTION_API_KEY | The API key for the Notion integration, required for all operations. | <required> | | NOTION_QUERY_APP_DATA_DIR | The root directory for storing local data, including the RAG index and synced content. Defaults to the 'rag-data' directory within the project root. | <project_root>/rag-data | | NOTION_SYNC_BATCH_SIZE | The number of pages to process in each synchronization cycle. | 30 | | NOTION_SYNC_INTERVAL_MS | The interval in milliseconds between synchronization cycles. | 900000 | | NOTION_GC_INTERVAL_MS | The interval in milliseconds for running the local file garbage collection task. | 21600000 |

Tools

query-datasource

Query a Notion Data Source - Gets a list of pages from a data source, identified by its URL (e.g., "collection://"). Supports filtering and sorting. The response is paginated; use 'start_cursor' for subsequent requests if 'next_cursor' is returned. Filters operate on properties and can be simple or compound (using "and"/"or"). Sorts operate on properties or timestamps. For performance, you can use 'filter_properties' to retrieve only necessary page properties. Refer to Notion API documentation for the exact filter and sort object structures.

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | data_source_url | string | The URL of the data source to query, e.g., "collection://f336d0bc-b841-465b-8045-024475c079dd". | | filter | object | A JSON filter object to apply. Example: {"property": "Done", "checkbox": {"equals": true}} or {"and": [...]}. | | sorts | array of object | An array of JSON sort objects. Example: [{"property": "Name", "direction": "ascending"}]. | | start_cursor | string | If provided, starts the query at the specified cursor. | | page_size | number | The number of items to return (max 100). | | filter_properties | array of string | An array of property IDs or names to return. If not provided, all properties are returned. |

fetch

Fetch Notion entities - Retrieves details about a Notion entity by its URL or ID. You can fetch the following types of entities:

• Page, i.e. from a block or a mention
• Database, i.e. from a block or a mention Use the "fetch" tool when you need to see the details of a Notion entity you already know exists and have its URL or ID. Provide the Notion entity's URL or ID in the id parameter. You must make multiple calls to the "fetch" tool if you want to fetch multiple entities. Content for pages that are returned use the enhanced Markdown format, which is a superset of the standard Markdown syntax. See the full spec in the description of the "create-pages" tool. Databases can have multiple data sources, which are collections of pages with the same schema. When fetching a database, the tool will return information about all its data sources. Examples of fetching entities:

1. Fetch a page by URL: { "id": "https://www.notion.so/workspace/Product-Requirements-1234567890abcdef" }
2. Fetch a page by ID (UUIDv4 with dashes): { "id": "12345678-90ab-cdef-1234-567890abcdef" }
3. Fetch a page by ID (UUIDv4 without dashes): { "id": "1234567890abcdef1234567890abcdef" }
4. Fetch a database: { "id": "https://www.notion.so/workspace/Projects-Database-abcdef1234567890" } Common use cases:

• "What are the product requirements still need to be implemented from this ticket https://notion.so/page-url?"
• "Show me the details of the project database at this URL"
• "Get the content of page 12345678-90ab-cdef-1234-567890abcdef"

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | id | string | The ID or URL of the Notion page or database to fetch. |

create-pages

Create pages in Markdown - Creates one or more Notion pages with specified properties and content. Use "create-pages" when you need to create one or more new pages that don't exist yet. Always include a title property under properties in each entry of the pages array. Otherwise, the page title will appear blank even if the page content is populated. Don't duplicate the page title at the top of the page's content. When creating pages under a Notion database, the property names must match the database's schema. Use the "fetch" tool with a Notion database URL to get the database schema. Or, look for existing pages under the database using the "search" tool then use the "fetch" tool to see the names of the property keys. One exception is the "title" property, which all pages have, but can be named differently in the schema of a database. For convenience, you can use the generic property name "title" in the "properties" object, and it will automatically be re-mapped to the actual name of the title property in the database schema when creating the page. All pages created with a single call to this tool will have the same parent. The parent can be a Notion page or database. If the parent is omitted, the pages will be created as standalone, workspace-level private pages and the person that created them can organize them as they see fit later. IMPORTANT: When specifying a parent database, use the appropriate ID format:

• Use "data_source_id" when you have a collection:// URL from the fetch tool (this is the most common case)
• Use "database_id" when you have a page URL for a database view (less common)
• Use "page_id" when the parent is a regular page Examples of creating pages:

1. Create a standalone page with a title and content: { "pages": [ { "properties": {"title":"Page title"}, "content": "# Section 1\nSection 1 content\n# Section 2\nSection 2 content" } ] }
2. Create a page under a database's data source (collection), e.g. using an ID from a collection:// URL provided by the fetch tool: { "parent": {"data_source_id": "f336d0bc-b841-465b-8045-024475c079dd"}, "pages": [ { "properties": { "Task Name": "Task 123", "Status": "In Progress", }, }, ], }
3. Create a page with an existing page as a parent: { "parent": {"page_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}, "pages": [ { "properties": {"title": "Page title"}, "content": "# Section 1\nSection 1 content\n# Section 2\nSection 2 content" } ] }

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | pages | array of object | The pages to create. | | parent | any | The parent under which the new pages will be created. This can be a page (page_id), a database page (database_id), or a data source/collection under a database (data_source_id). If omitted, the new pages will be created as private pages at the workspace level. Use data_source_id when you have a collection:// URL from the fetch tool. |

notion-update-page

Update Notion page - Update a Notion page's properties or content. Notion page properties are a JSON map of property names to SQLite values. For pages in a database, use the SQLite schema definition shown in . For pages outside of a database, the only allowed property is "title", which is the title of the page in inline markdown format. Notion page content is a string in Notion-flavored Markdown format. See the "create-pages" tool description for the full enhanced Markdown spec. Before updating a page's content with this tool, use the "fetch" tool first to get the existing content to find out the Markdown snippets to use in the "replace_content_range" or "insert_content_after" commands. IMPORTANT: Some property types require expanded formats:

• Date properties: Split into "date:{property}:start", "date:{property}:end" (optional), and "date:{property}:is_datetime" (0 or 1)
• Place properties: Split into "place:{property}:name", "place:{property}:address", "place:{property}:latitude", "place:{property}:longitude", and "place:{property}:google_place_id" (optional) Number properties accept JavaScript numbers (not strings). Use null to remove a property's value. Boolean values like "YES" are supported for checkbox properties.

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | data | any | |

search

Search Notion workspace - Perform a semantic search over your entire Notion workspace. You can use search when you need to find information which is not already available via other tools, and you don't know where it's located. If initial results do not contain all the information you need, you can try more specific queries. After obtaining search results, if the user asks for the full contents of a page or database, use the "fetch" tool. This tool only shows some details like a highlight and the URL and title of each search result.

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | query | string | Semantic search query over your entire Notion workspace. For best results, don't provide more than one question per tool call. | | page_url | string | Optionally, provide the URL or ID of a page to search within. This will perform a semantic search over the content within and under the specified page. | | teamspace_id | string | Optionally, provide the ID of a teamspace to restrict search results to. This will perform a search over content within the specified teamspace only. | | data_source_url | string | Optionally, provide the URL of a Data source to search. This will perform a semantic search over the pages in the Data Source. |

Other MCP Servers

This monorepo contains several other MCP server packages available on npm. Each provides a distinct set of tools for use with the Model Context Protocol.

• @mcp-monorepo/confluence: MCP server for Confluence API tools
• @mcp-monorepo/file-browser: MCP server for file system browsing and manipulation (search, ls, tree, grep, open, write, move, mkdir)
• @mcp-monorepo/ics: MCP server for calendar tools using ICS/ical feeds
• @mcp-monorepo/jira: MCP server for Jira tools (JQL, issue management, etc.).
• @mcp-monorepo/location: MCP server for location-based tools using IP address lookup
• @mcp-monorepo/mail: MCP server for mail tools (fetch, read, search, mark as seen).
• @mcp-monorepo/npm: MCP server for npm command tools (run scripts, install packages, list scripts)
• @mcp-monorepo/slack: Slack MCP to access workspace without bot account or app
• @mcp-monorepo/weather: Weather MCP tools (geocoding, weather-by-coords) for ModelContextProtocol.

Recent Changes

Version 1.3.1

• fd22b00: Fixed yarn versioning during publish

Version 1.3.0

• 35ada47: add update-page tool and implement property update parsing; rename create-pages tool

Version 1.2.0

• b49ff85: add notion create-pages tool with markdown content, register in server, enhance property parsing

Authors

• The MCP Monorepo Team

License

This project is licensed under the AGPL-3.0-only License. See the LICENSE file for details.