README.md
Enables AI agents to search, create, and manage Notion pages and databases.
MCP Server for Notion
This tool provides the Notion API as an MCP (Model Context Protocol) server. It enables AI agents to search, view, create, and update Notion pages, as well as operate on databases.
Features
Page & Database Operations
Supports major operations such as search, retrieval, creation, updates, and appending blocks.
File-based Operations
Drastically reduces LLM token usage by saving/loading page content (JSON) to/from files.
Response Extraction (extract)
Optimizes context size by extracting only the necessary properties from the API response.
Quick Start
Local Development Environment
Install:
git clone https://github.com/acckkiie/mcp-notion cd mcp-notion npm installConfigure: Copy
.env.exampleto create.envand set your Notion API key.cp .env.example .env # Edit .env: NOTION_API_KEY=secret_...Run:
npm run dev
Image Build
npm run build
docker build -t mcp-notion:latest .
MCP Client Configuration
Via Docker (Recommended)
Using Docker reduces environment dependencies and enables security control via proxy.
{
"mcpServers": {
"mcp-notion": {
"disabled": false,
"command": "bash",
"args": [
"-c",
"docker compose -f /path/to/mcp-notion/docker-compose.yml down 2>/dev/null; docker compose --env-file /path/to/mcp-notion/.env -f /path/to/mcp-notion/docker-compose.yml run --rm -i mcp-notion"
],
"env": {
"HOST_WORKSPACE_PATH": "/path/to/your/workspace"
}
}
}
}
Local Execution
{
"mcpServers": {
"notion": {
"command": "node",
"args": [
"/path/to/mcp-notion/build/index.js"
],
"env": {
"NOTION_API_KEY": "secret_...",
"HOST_WORKSPACE_PATH": "/path/to/your/workspace"
}
}
}
}
License
Tools (5)
searchSearch for Notion pages and databases.retrieveRetrieve content from a specific Notion page or database.createCreate a new page or database entry in Notion.updateUpdate an existing Notion page or database entry.append_blockAppend new blocks to a Notion page.Environment Variables
NOTION_API_KEYrequiredYour Notion integration secret key.HOST_WORKSPACE_PATHrequiredLocal path for file-based operations to save/load page content.Configuration
claude_desktop_config.json
{"mcpServers": {"notion": {"command": "node", "args": ["/path/to/mcp-notion/build/index.js"], "env": {"NOTION_API_KEY": "secret_...", "HOST_WORKSPACE_PATH": "/path/to/your/workspace"}}}}Try it
→Search for the project roadmap page in my Notion workspace.
→Retrieve the content of the 'Meeting Notes' database entry from yesterday.
→Create a new task page in the 'Engineering' database with the title 'Fix API bug'.
→Append a summary of our recent discussion to the 'Project Alpha' page.