Notion MCP Server
A Model Context Protocol server for Notion API integration, providing tools to create, retrieve, and update Notion pages.
Features
- Create Page: Create new pages in databases or as child pages
- Retrieve Page: Get page properties and metadata
- Update Page: Modify page properties, icons, covers, and archive status
- Retrieve Page Property: Get detailed property information with pagination support
Installation
cd backend/notion-mcp
npm install
Configuration
Create a .env file with your Notion API key:
NOTION_API_KEY=your_notion_integration_token_here
NOTION_VERSION=2022-06-28
PORT=3003
Getting a Notion API Key
- Go to Notion Developers
- Create a new integration
- Copy the "Internal Integration Token"
- Share your databases/pages with the integration
Usage
STDIO Transport (Development)
npm run dev:stdio
HTTP Transport (Production)
npm run dev:http
# or
npm start
Available Tools
notion_create_page
Creates a new page in Notion.
Parameters:
parent(required): Parent page or database IDproperties(required): Page properties matching parent schemachildren(optional): Page content as block objectsicon(optional): Page icon (emoji or external URL)cover(optional): Page cover image
Example:
{
"parent": {
"type": "database_id",
"database_id": "d9824bdc-8445-4327-be8b-5b47500af6ce"
},
"properties": {
"Name": {
"title": [{"text": {"content": "New Page"}}]
}
},
"icon": {
"type": "emoji",
"emoji": "📝"
}
}
notion_retrieve_page
Retrieves a Notion page by ID.
Parameters:
page_id(required): The page ID to retrievefilter_properties(optional): Specific property IDs to return
notion_update_page
Updates page properties and metadata.
Parameters:
page_id(required): The page ID to updateproperties(optional): Properties to updatein_trash(optional): Archive/restore the pageicon(optional): Update page iconcover(optional): Update page cover
notion_retrieve_page_property
Retrieves detailed property information with pagination.
Parameters:
page_id(required): The page IDproperty_id(required): The property IDpage_size(optional): Number of items per page (max 100)start_cursor(optional): Pagination cursor
Building
npm run build
Development
npm run watch # Watch mode for TypeScript compilation
Client Configuration
For HTTP transport, add to your MCP client config:
{
"mcpServers": {
"notion": {
"url": "http://localhost:3003/mcp"
}
}
}
For STDIO transport:
{
"mcpServers": {
"notion": {
"command": "node",
"args": ["./dist/index.js"]
}
}
}
Health Check
When running HTTP transport:
curl http://localhost:3003/health
Error Handling
The server provides detailed error messages for:
- Missing API keys
- Invalid page/database IDs
- Permission errors
- Malformed requests
- Notion API rate limits
License
MIT