Description
Une implémentation de serveur Model Context Protocol (MCP) qui permet aux assistants IA d'interagir avec l'API Notion.
Type
Notion MCP Server
Notion MCP Server is a Model Context Protocol (MCP) server implementation that enables AI assistants to interact with Notion's API. This production-ready server provides a complete set of tools and endpoints for reading, creating, and modifying Notion content through natural language interactions.
🚧 Active Development: Database support is now available! If you find this project useful, please consider giving it a star - it helps me know that this work is valuable to the community and motivates further development.
📑 Table of Contents
- Getting Started & Integration
- Setup Process
- Cursor Integration
- Claude Desktop Integration
- Features
- Documentation
- Available Tools
- Available Resources
- Development
- Technical Details
- Troubleshooting
- Contributing
- License
🚀 Getting Started & Integration
Setup Process
-
Obtain a Notion API Key
- Create an integration at Notion Developers
- Copy your API key
-
Enable Integration for Your Pages
- Select an existing page or create a new one in Notion
- Click the "..." menu in the top right corner
- Go to "Connections"
- Find and enable your integration from the list
图片已屏蔽 (相对路径) -
Choose Your Integration Method
- Follow one of the integration options below based on your preferred MCP client
-
Ask Your AI Assistant to Interact with Notion
- "Create a new page with today's tasks"
- "Update my meeting notes in Notion"
- "Add bullet points to my meeting notes page"
- "Create a new database for tracking projects"
- "Add new entries to my task database"
Cursor Integration
Method 1: Using mcp.json
- Create or edit the
.cursor/mcp.json
file in your project directory:
{
"mcpServers": {
"notion-mcp-server": {
"command": "env NOTION_TOKEN=YOUR_KEY NOTION_PAGE_ID=YOUR_PAGE_ID npx",
"args": ["-y", "notion-mcp-server"]
}
}
}
- Replace
YOUR_KEY
andYOUR_PAGE_ID
with your actual Notion API key and page ID - Restart Cursor to apply the changes
Method 2: Manual Mode
- Open Cursor and go to Settings
- Navigate to the "MCP" or "Model Context Protocol" section
- Click "Add Server" or equivalent
- Enter the following command in the appropriate field:
env NOTION_TOKEN=YOUR_KEY NOTION_PAGE_ID=YOUR_PAGE_ID npx -y notion-mcp-server
- Replace
YOUR_KEY
andYOUR_PAGE_ID
with your actual Notion API key and page ID - Save the settings and restart Cursor if necessary
Claude Desktop Integration
- Create or edit the
mcp.json
file in your configuration directory:
{
"mcpServers": {
"notion-mcp-server": {
"command": "npx",
"args": ["-y", "notion-mcp-server"],
"env": {
"NOTION_TOKEN": "YOUR_KEY",
"NOTION_PAGE_ID": "YOUR_PAGE_ID"
}
}
}
}
- Replace
YOUR_KEY
andYOUR_PAGE_ID
with your actual Notion API key and page ID - Restart Claude Desktop to apply the changes
🌟 Features
- 📝 Notion Integration - Interact with Notion databases, pages, and blocks
- 🔌 Universal MCP Compatibility - Works with all MCP clients including Cursor, Claude Desktop, Cline, and Zed
- 🔍 Data Retrieval - Fetch information from Notion pages, blocks, and databases
- ✏️ Content Creation - Create and update Notion pages and blocks
- 📊 Block Management - Append, update, and delete blocks within Notion pages
- 💾 Database Operations - Create, query, and update databases
- 🔄 Batch Operations - Perform multiple operations in a single request
- 🗑️ Archive & Restore - Archive and restore Notion pages
- 🔎 Search Functionality - Search Notion pages and databases by title
📚 Documentation
Available Tools
The server provides the following tools for interacting with Notion:
Page Operations
create_page
Create a new page in Notion with specified content
update_page_properties
Update the properties of an existing Notion page
archive_page
Archive (move to trash) a Notion page by ID
restore_page
Restore a previously archived Notion page by ID
search_pages
Search for pages and databases in Notion by title
Database Operations
create_database
Create a new database in Notion with specified properties
query_database
Query a database in Notion with filters, sorts, and pagination
update_database
Update an existing database's properties, title, or description
Block Operations
retrieve_block
Retrieve a block from Notion by ID
retrieve_block_children
Retrieve the children of a block from Notion
append_block_children
Append child blocks to a parent block in Notion
update_block
Update a block's content in Notion
delete_block
Delete (move to trash) a block in Notion
Batch Operations
batch_append_block_children
Append children to multiple blocks in a single operation
batch_update_blocks
Update multiple blocks in a single operation
batch_delete_blocks
Delete multiple blocks in a single operation
batch_mixed_operations
Perform a mix of append, update, and delete operations in a single request
Available Resources
The server currently does not expose any resources, focusing instead on tool-based operations.
🛠 Development
-
Clone the Repository
git clone https://github.com/awkoy/notion-mcp-server.git cd notion-mcp-server
-
Install Dependencies
npm install
-
Set Up Environment Variables
- Create a
.env
file with:NOTION_TOKEN=your_notion_api_key NOTION_PAGE_ID=your_notion_page_id
- Create a
-
Build the Project
npm run build
-
Run the Inspector
npm run inspector
🔧 Technical Details
- Built using TypeScript and the MCP SDK (version 1.7.0+)
- Uses the official Notion API client (@notionhq/client v2.3.0+)
- Follows the Model Context Protocol specification
- Implements tools for CRUD operations on Notion pages, blocks, and databases
- Supports efficient batch operations for performance optimization
- Validates input/output with Zod schemas
❓ Troubleshooting
-
Common Issues
- Authentication Errors: Ensure your Notion token has the correct permissions and integration is enabled for your pages/databases
- Page Access Issues: Make sure your integration has been added to the pages you're attempting to access
- Rate Limiting: Notion API has rate limits - use batch operations to optimize requests
-
Getting Help
- Create an issue on the GitHub repository
- Check the Notion API documentation
- Visit the MCP community channels for assistance
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.