Simple Notion MCP Server
About
Notion MCP server that uses Markdown for better LLM support
Details
- Author
- larryhudson
- Downloads
- 157
- Categories
- Knowledge Base
Jump to
- Converts Notion pages to clean, readable Markdown format.
- Preserves rich text formatting (bold, italic, strikethrough, code).
- Retrieves page metadata and all blocks recursively.
- Built with TypeScript, MCP, and the official Notion API Client.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Simple Notion MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Create a Notion integration at https://www.notion.so/my-integrations and obtain an API token. Set the token as the NOTION_TOKEN environment variable or in a .env file. Share any Notion pages you want to access with your integration. Then configure your MCP-compatible application (VS Code, Claude, etc.) to run the server via npx -y @larryhudson/simple-notion-mcp-server with the token. Use the get_page tool with a page_id parameter to retrieve and render a page as Markdown.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"simple notion mcp server": {
"simple-notion-mcp-server": {
"command": "npx",
"args": [
"@modelcontextprotocol/inspector",
"npx",
"tsx",
"src/index.ts"
]
}
}
}
}McpServers
{
"simple-notion-mcp-server": {
"command": "npx",
"args": [
"@modelcontextprotocol/inspector",
"npx",
"tsx",
"src/index.ts"
]
}
}Simple Notion MCP Server
Overview
This project implements a Model Context Protocol (MCP) server that acts as a bridge between AI assistants and the Notion API. Unlike the official Notion MCP server which returns large JSON blobs, this server renders Notion pages as Markdown, making them much more efficient for LLMs to process and understand.
Features
- Markdown Rendering: Converts Notion pages to clean, readable Markdown format
- Rich Text Support: Preserves formatting for bold, italic, strikethrough, and code elements
Setup
1. Create a Notion integration and get an API token from https://www.notion.so/my-integrations
2. Set the token as an environment variable:
export NOTION_TOKEN=your-notion-api-token
Alternatively, you can create a .env file in your project with:
NOTION_TOKEN=your-notion-api-token
3. Make sure to share any Notion pages you want to access with your integration
Usage
Using with VS Code
Add this to your settings JSON file:
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "notion_token",
"description": "Notion API Token",
"password": true
}
],
"servers": {
"notion": {
"command": "npx",
"args": [
"-y",
"@larryhudson/simple-notion-mcp-server"
],
"env": {
"NOTION_TOKEN": "${input:notion_token}"
}
}
}
}
}
Using with Claude or other MCP-compatible applications
Add this to your MCP configuration JSON file:
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@larryhudson/simple-notion-mcp-server"],
"env": {
"NOTION_TOKEN": "<YOUR_NOTION_API_TOKEN>"
}
}
}
}
Available Tools
get_page
Retrieves a Notion page by ID and renders it as Markdown.
Parameters:
- page_id: The ID of the Notion page to retrieve
Example:
{
"page_id": "83c75a5b7a324be29d454536f2345678"
}
How It Works
The server processes Notion pages through these steps:
1. Fetches page metadata using the Notion API
2. Retrieves all blocks from the page (with recursive fetching of child blocks)
3. Formats blocks into Markdown, maintaining structure and formatting
4. Returns a clean Markdown representation of the page
Technical Details
Built with:
- Model Context Protocol (MCP): Framework for allowing AI assistants to interact with external tools
- Notion API Client: Official client for communicating with Notion
- TypeScript: For type safety and better developer experience
Development
You can use the Model Context Protocol inspector to try out the server:
npx @modelcontextprotocol/inspector npx tsx src/index.ts
Limitations and Future Improvements
- Currently only supports retrieving pages (not updating or creating)
- Image handling could be improved in future updates (e.g. rendering images as base64 image blocks)
License
MIT
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
