🚀 Notion MCP Server
A powerful Model Context Protocol (MCP) server that connects AI assistants like Claude to your Notion workspace. Seamlessly search, create, and manage your Notion content through natural language conversations!
✨ What This Does
Transform your AI assistant into a Notion powerhouse! With this MCP server, you can:
- 🔍 Search through all your Notion pages and databases
- 📝 Create new pages, databases, and content
- ✏️ Update existing pages and properties
- 📊 Query databases with complex filters
- 🔗 Manage your entire Notion workspace through conversation
🎯 Quick Start
1. Prerequisites
- Python 3.8 or higher
- A Notion workspace
- Nango account (for OAuth authentication)
- Claude Desktop app (for AI integration)
2. Installation
# Clone or download the files
git clone <your-repo-url>
cd notion-mcp-server
# Install dependencies
uv sync
3. Notion Setup
-
Create a Notion Integration:
- Go to https://www.notion.so/my-integrations
- Click "New integration"
- Name it (e.g., "Claude MCP Integration")
- Select your workspace
- Set capabilities:
- ✅ Read content
- ✅ Insert content
- ✅ Update content
- Save and copy your integration token
-
Share Pages with Integration:
- Open any Notion page you want to access
- Click "Share" → "Invite"
- Select your integration
- Repeat for all pages/databases you want to use
4. Nango Setup (OAuth)
- Create Nango Account: https://nango.dev
- Add Notion Integration in your Nango dashboard
- Configure OAuth with your Notion integration credentials
- Get your Nango credentials (Base URL, Secret Key, Connection ID)
5. Environment Configuration
Create a .env file with your credentials:
# Nango OAuth Configuration
NANGO_BASE_URL=https://api.nango.dev
NANGO_SECRET_KEY=your_nango_secret_key_here
NANGO_CONNECTION_ID=your_connection_id_here
NANGO_INTEGRATION_ID=notion
# Optional: Direct Notion Token (if not using Nango)
# NOTION_TOKEN=your_direct_notion_token_here
6. Claude Desktop Configuration
Add this to your Claude Desktop configuration file:
On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"notion": {
"command": "uvx",
"args": ["git+https://github.com/ampcome-mcps/notion-mcp.git"],
"env": {
"NANGO_BASE_URL": "https://api.nango.dev",
"NANGO_SECRET_KEY": "your_nango_secret_key",
"NANGO_CONNECTION_ID": "your_connection_id",
"NANGO_INTEGRATION_ID": "notion"
}
}
}
}
7. Test the Connection
# Test the server directly
python notion-mcp-server.py
# Or restart Claude Desktop and try asking:
# "Search my Notion for meeting notes"
# "Create a new task in my project database"
🛠️ Available Tools
| Tool | Description | Example Use |
|---|---|---|
notion_search | Search across all content | "Find pages about project planning" |
notion_get_database | Get database info | "Show me my tasks database structure" |
notion_query_database | Query with filters | "Show incomplete tasks due this week" |
notion_create_database | Create new databases | "Create a CRM database with contacts" |
notion_get_page | Get page details | "Show me the content of my meeting notes" |
notion_create_page | Create new pages | "Add a new task to my project database" |
notion_update_page | Update existing pages | "Mark this task as completed" |
notion_get_block_children | Get page content | "Read the content of this page" |
notion_append_blocks | Add content to pages | "Add meeting notes to this page" |
notion_get_current_user | Get integration info | "Check my Notion connection status" |
💬 Example Conversations with Claude
Once configured, you can have natural conversations like:
Task Management
You: "Show me all my incomplete tasks"
Claude: [Queries your tasks database and shows open items]
You: "Create a new task called 'Review MCP integration' due next Friday"
Claude: [Creates the task with proper due date]
You: "Mark the first task as completed"
Claude: [Updates the task status to Done]
Content Creation
You: "Create a meeting notes page for today's standup"
Claude: [Creates a new page with meeting template]
You: "Add action items from our discussion to that page"
Claude: [Appends bullet points with the action items]
Research & Organization
You: "Search for all pages mentioning 'API documentation'"
Claude: [Finds and lists relevant pages]
You: "Create a new database to track our API endpoints"
Claude: [Creates a structured database with relevant properties]
🔧 Troubleshooting
Common Issues
"Authentication Error"
- Check your
.envfile has correct Nango credentials - Verify your Nango integration is active
- Ensure your Notion integration has proper capabilities
"Page not found" errors
- Make sure you've shared the page/database with your integration
- Check the page/database ID is correct
- Verify the integration has read access
Claude can't find the server
- Check the absolute path in
claude_desktop_config.jsonis correct - Ensure Python is in your system PATH
- Try running the server manually first to test
"No access token found"
- Verify Nango connection is working
- Check your
NANGO_CONNECTION_IDmatches your actual connection - Try refreshing your Nango integration
Debug Mode
Run with verbose logging:
python notion-mcp-server.py --debug
Manual Testing
Test individual functions:
from notion_mcp_server import NotionClient
client = NotionClient()
user = client.get_current_user()
print(f"Connected as: {user.get('name')}")
🔒 Security Notes
- Never commit your
.envfile to version control - Keep your Nango secret key secure
- Only share Notion pages that the integration needs access to
- Regularly review your integration's access in Notion settings
📁 File Structure
notion-mcp/
├── main.py # Main MCP server
├── pyproject.toml # Python dependencies
├── .env.example
├── .env # Your credentials (don't commit!)
├── README.md # This file
🆘 Getting Help
- Check the logs - Look for error messages in Claude Desktop or terminal
- Verify permissions - Ensure your integration can access the pages
- Test manually - Run the server directly to isolate issues
- Check Notion status - Sometimes Notion API has outages
🎉 What's Next?
Once you're up and running:
- Try creating complex database queries
- Set up automated content creation workflows
- Use Claude to help organize and restructure your Notion workspace
- Explore advanced filtering and sorting options
📄 License
This project is open source. Feel free to modify and adapt for your needs!
Happy Notion-ing with Claude! 🎊
Made with ❤️ for the AI-powered productivity enthusiasts
