Notion MCP Server

A Model Context Protocol (MCP) server that provides access to your Notion workspace. This server allows you to ask natural language questions and get comprehensive answers by searching through your entire Notion workspace, making your Notion data accessible to MCP-compatible applications like Roo Code and other LLM clients.

Features

Natural Language Queries: Ask questions in plain English about any content in your Notion workspace
Comprehensive Search: Searches through your entire Notion workspace, not just a subset
Page Hierarchy Mapping: Automatically discovers and maps all pages with their hierarchical relationships
Intelligent Caching: Caches page mappings to reduce API calls and improve performance
Rich Content Retrieval: Gets full content from the most relevant pages with proper formatting
Source Citations: Always includes links back to the original Notion pages
Rich Text Support: Handles various Notion block types including headings, lists, code blocks, and more
Advanced Page Discovery: Find pages by title, path, or hierarchical structure

How It Works

Page Hierarchy Mapping

The server automatically builds a comprehensive map of your entire Notion workspace:

Discovery: Fetches all pages and databases from your workspace
Hierarchy Building: Constructs parent-child relationships between pages
Path Mapping: Creates full paths from root to each page (e.g., "Projects > Q4 Planning > Meeting Notes")
Intelligent Caching: Stores mappings in src/notion_mcp_server/resources/page_cache.json with configurable expiration
Runtime Updates: Automatically refreshes cache when pages are created or updated

Query Processing

The server provides multiple tools for interacting with your Notion content:

ask-notion: Natural language queries

Takes your natural language question
Searches through your entire Notion workspace for relevant content
Retrieves full content from the most relevant pages
Combines the information into a comprehensive answer
Provides source links to all pages used in the response

Additional Tools: Page management and discovery

list-notion-pages: Browse all pages with hierarchical structure
find-notion-page: Find specific pages by title or path
write-to-notion: Create or update pages (with automatic cache refresh)
refresh-notion-cache: Manually refresh the page mapping cache

Components

Resources

The server exposes Notion pages as resources with a custom notion:// URI scheme:

Each page is accessible via notion://page/{page_id}
Resources include page titles and descriptions
Content is returned as formatted markdown text

Tools

The server implements several tools for comprehensive Notion interaction:

ask-notion: Ask any question about your Notion content

Takes a natural language question as input
Searches your entire Notion workspace for relevant information
Returns a comprehensive answer with source citations
Optionally limits the number of pages to include full content from (default: 5 most relevant)

write-to-notion: Create or update Notion pages

Create new pages at the workspace level or under specific parent pages
Update existing pages by ID
Supports markdown formatting for content
Automatically refreshes page mapping cache after changes

list-notion-pages: Browse your workspace structure

Lists all pages with hierarchical indentation
Filter by depth, archived status, and other criteria
Shows page IDs, paths, and URLs for easy reference

find-notion-page: Locate specific pages

Search by exact or fuzzy title matching
Find pages by hierarchical path (e.g., ["Projects", "Q4 Planning"])
Returns detailed page information including full path and metadata

refresh-notion-cache: Update page mappings

Forces a refresh of the cached page hierarchy
Useful when pages have been added/modified outside the server
Provides summary statistics about your workspace structure

Setup

Prerequisites

Python 3.10 or higher
uv package manager
A Notion account with pages you want to access
A Notion integration token

Installation

Clone this repository:

git clone https://github.com/alecgrater/notion-mcp-server.git
cd notion-mcp-server

Install dependencies using uv:

uv sync --dev --all-extras

Create a Notion integration:

Go to https://www.notion.so/my-integrations
Click "New integration"
Give it a name (e.g., "MCP Server")
Select the workspace you want to access
Copy the "Internal Integration Token"

Set up environment variables:

cp .env.example .env
# Edit .env and add your Notion token

Share pages with your integration:

In Notion, go to the pages you want the MCP server to access
Click "Share" in the top right
Click "Invite" and select your integration
Grant appropriate permissions

Configuration

For Roo Code

Add the server to your Roo Code MCP configuration:

{
  "mcpServers": {
    "notion": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/notion-mcp-server",
        "run",
        "notion-mcp-server"
      ],
      "env": {
        "NOTION_TOKEN": "your_notion_integration_token_here"
      }
    }
  }
}

For Other LLM Clients

For other MCP-compatible clients, configure the server with:

Command: uv
Args: ["--directory", "/path/to/notion-mcp-server", "run", "notion-mcp-server"]
Environment: Set NOTION_TOKEN to your integration token

Alternatively, if you have a .env file in the project directory, you can omit the environment configuration:

{
  "mcpServers": {
    "notion": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/notion-mcp-server",
        "run",
        "notion-mcp-server"
      ]
    }
  }
}

Usage

Once configured, you can use the Notion MCP server in your preferred LLM client by asking questions about your Notion content:

"What are my current project priorities?"
"Find information about the Q4 planning meeting"
"What feedback did we get from the customer interviews?"
"Show me my notes about the new product features"
"What are the action items from last week's meetings?"

The server will automatically:

Search through your entire Notion workspace
Find the most relevant pages
Extract and combine the relevant information
Provide a comprehensive answer with links to source pages

Development

Running the Server

For development, you can run the server directly:

uv run notion-mcp-server

Testing

Basic Tests

Run basic functionality tests to verify the page mapping system is properly set up:

uv run pytest tests/test_basic_pytest.py -v

This will test:

Module imports and dependencies
Page data structure creation
Resources folder and cache file existence

Integration Tests

Test with your actual Notion workspace (requires NOTION_TOKEN environment variable):

uv run pytest tests/test_page_mapper_pytest.py -v

This will:

Connect to your Notion workspace
Fetch and map all pages with hierarchy
Test caching functionality
Verify search and discovery features

Run All Tests

To run all tests at once: ``bash uv run pytest tests/ -v ``

VSCode Integration

The tests are now pytest-compatible and should work directly in VSCode's testing interface. Make sure VSCode is using the correct Python interpreter (.venv/bin/python) for the project.

MCP Inspector

You can also test the server using the MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory . run notion-mcp-server

This will open a web interface where you can test the server's tools and resources interactively.

Building and Publishing

To prepare the package for distribution:

Sync dependencies and update lockfile:

uv sync

Build package distributions:

uv build

Publish to PyPI:

uv publish

Troubleshooting

Common Issues

"NOTION_TOKEN environment variable is required"

Make sure you've set the NOTION_TOKEN environment variable
Check that your .env file is in the correct location
Verify the token is valid and hasn't expired

"No relevant information found"

Ensure your integration has been shared with the pages you want to search
Check that the pages contain the content you're looking for
Try rephrasing your question or using broader terms

"Error searching Notion"

Verify your integration token is correct and hasn't expired
Check that your integration has the necessary permissions
Ensure you have an active internet connection

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, use the MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory . run notion-mcp-server

Security

Keep your Notion integration token secure and never commit it to version control
Only share your integration with pages that you want the MCP server to access
Regularly review and rotate your integration tokens

notion-mcp-server