Notion MCP Server V2 🚀

1# Notion MCP Server V2 🚀
2 
3A comprehensive **Model Context Protocol (MCP) server** for Notion integration with enhanced functionality, robust error handling, production-ready features, and **bulletproof validation**.
4 
5## ✨ Features
6 
7### 🔧 **Core Operations**
8 
9- ✅ **Search**: Find pages and databases with advanced filtering
10- ✅ **Page Operations**: Create, read, update pages with full content support
11- ✅ **Content Management**: Add paragraphs, headings, bullet points, todos, **links, and bookmarks**
12- ✅ **Database Operations**: List and query databases
13 
14### 🔗 **Advanced Content Types** _(NEW)_
15 
16- ✅ **Bookmarks**: Add external website links with URL validation
17- ✅ **Link to Page**: Create internal links between Notion pages
18- ✅ **Rich Content**: Support for all major Notion block types
19- ✅ **Content Splitting**: Automatic handling of long content (2000+ chars)
20 
21### 📊 **Analytics & Insights**
22 
23- ✅ **Workspace Analytics**: Total pages, databases, recent activity
24- ✅ **Content Analytics**: Structure analysis and metrics
25- ✅ **Activity Tracking**: Recent edits and usage patterns
26- ✅ **Performance Metrics**: Optimized with configurable timeouts
27 
28### 🔄 **Bulk Operations** _(OPTIMIZED)_
29 
30- ✅ **Smart Pagination**: Prevents timeouts with configurable limits
31- ✅ **Bulk Content Addition**: Add multiple content blocks at once
32- ✅ **Bulk Page Operations**: Create and manage multiple pages
33- ✅ **Performance Controls**: Optional block counts for faster responses
34 
35### 🌐 **API Interfaces**
36 
37- ✅ **FastAPI REST API**: Production-ready HTTP endpoints
38- ✅ **Interactive CLI**: Command-line interface for direct usage
39- ✅ **MCP Compatible**: Full Model Context Protocol support
40- ✅ **Agent Integration**: Unified endpoint for AI agents
41 
42### 🛡️ **Production Features** _(ENHANCED)_
43 
44- ✅ **Bulletproof Validation**: Comprehensive input validation and error handling
45- ✅ **Configuration Management**: Environment-based settings
46- ✅ **Smart Error Recovery**: Detailed error messages and recovery guidance
47- ✅ **Health Checks**: Monitoring and status endpoints with feature detection
48- ✅ **Structured Logging**: Configurable logging with performance insights
49- ✅ **CORS Support**: Cross-origin resource sharing
50- ✅ **Timeout Optimization**: Dynamic timeouts based on operation complexity
51 
52### 🧪 **Testing & Quality** _(COMPREHENSIVE)_
53 
54- ✅ **46KB Test Suite**: 1,158 lines of comprehensive tests
55- ✅ **13+ Test Categories**: Core, content, bulk, links, analytics, edge cases
56- ✅ **Validation Testing**: Tests for all error scenarios and edge cases
57- ✅ **Performance Testing**: Timeout and optimization validation
58- ✅ **Detailed Reporting**: JSON reports with timing and categorization
59 
60## 🏗️ Architecture
61 
62```
63notion_mcp_server/
64├── 📄 __init__.py           # Package initialization
65├── 🔧 config.py             # Configuration management
66├── 🌐 api_serverV2.py       # FastAPI REST API server (49KB)
67├── 💻 serverV2.py           # Interactive CLI server
68├── ⚙️ core_operations.py    # Basic CRUD operations
69├── 📊 analytics_operations.py # Analytics and metrics
70├── 🔄 bulk_operations.py    # Bulk processing
71├── ✏️ update_operations.py  # Content updates (35KB)
72├── 🛠️ notion_utils.py      # Utility functions
73├── 🧪 test_server.py        # Comprehensive test suite (48KB)
74└── 📖 README.md             # This file
75```
76 
77## 📦 Installation
78 
79### Prerequisites
80 
81- Python 3.8+
82- Notion account with integration token
83- pip or conda package manager
84 
85### Setup
86 
871. **Install Dependencies**
88 
89```bash
90pip install notion-client fastapi uvicorn python-dotenv pydantic requests
91```
92 
932. **Environment Configuration**
94   Create a `.env` file in your project root:
95 
96```env
97# Required
98NOTION_TOKEN=ntn_your_integration_token_here
99 
100# Optional Server Settings
101HOST=0.0.0.0
102PORT=8081
103DEBUG=false
104 
105# Optional Feature Settings
106MAX_PAGE_SIZE=100
107DEFAULT_PAGE_SIZE=20
108MAX_CONTENT_LENGTH=2000
109ENABLE_ANALYTICS=true
110ENABLE_BULK_OPERATIONS=true
111 
112# Optional Logging
113LOG_LEVEL=INFO
114```
115 
1163. **Get Your Notion Token**
117 
118- Go to [Notion Integrations](https://www.notion.so/profile/integrations)
119- Create a new integration
120- Copy the token (starts with `ntn_`)
121- Share your pages/databases with the integration
122 
123## 🚀 Usage
124 
125### 1. FastAPI Server (Production)
126 
127**Start the server:**
128 
129```bash
130python -m notion_mcp_server.api_serverV2
131```
132 
133**Server will be available at:**
134 
135- API: `http://localhost:8081`
136- Documentation: `http://localhost:8081/docs`
137- Health Check: `http://localhost:8081/health`
138 
139### 2. Interactive CLI
140 
141```bash
142python -m notion_mcp_server.serverV2
143```
144 
145### 3. Python Integration
146 
147```python
148from notion_mcp_server import ComprehensiveNotionServer
149import asyncio
150 
151async def example():
152    server = ComprehensiveNotionServer("your_notion_token")
153    await server.core_ops.search_content("search term")
154 
155asyncio.run(example())
156```
157 
158## 📚 API Documentation
159 
160### 🔍 **Search Endpoint**
161 
162```http
163POST /api/search
164Content-Type: application/json
165 
166{
167  "query": "search term",
168  "page_size": 10
169}
170```
171 
172### 📄 **Create Page**
173 
174```http
175POST /api/page/create
176Content-Type: application/json
177 
178{
179  "title": "My New Page",
180  "content": "Initial content",
181  "parent_id": "optional-parent-page-id"
182}
183```
184 
185### 📖 **Read Page**
186 
187```http
188POST /api/page/read
189Content-Type: application/json
190 
191{
192  "identifier": "page-id-or-title"
193}
194```
195 
196### ✏️ **Add Content** _(ENHANCED)_
197 
198```http
199POST /api/page/add-content
200Content-Type: application/json
201 
202{
203  "page_id": "page-id",
204  "content_type": "paragraph",
205  "content": "New paragraph content"
206}
207```
208 
209**Supported content types:**
210 
211- `paragraph` - Regular text
212- `heading_1` - Large heading
213- `heading_2` - Medium heading
214- `heading_3` - Small heading
215- `bulleted_list_item` - Bullet point
216- `to_do` - Checkbox item
217- `bookmark` - External website link _(NEW)_
218- `link_to_page` - Internal page link _(NEW)_
219 
220### 🔗 **Link Content Types** _(NEW)_
221 
222**Add Bookmark (External Link):**
223 
224```http
225POST /api/page/add-content
226Content-Type: application/json
227 
228{
229  "page_id": "page-id",
230  "content_type": "bookmark",
231  "content": "OpenAI Website",
232  "url": "https://www.openai.com"
233}
234```
235 
236**Add Link to Page (Internal Link):**
237 
238```http
239POST /api/page/add-content
240Content-Type: application/json
241 
242{
243  "page_id": "page-id",
244  "content_type": "link_to_page",
245  "content": "Link to related page",
246  "page_reference": "target-page-id-or-title"
247}
248```
249 
250### 🔄 **Bulk Content Addition** _(ENHANCED)_
251 
252```http
253POST /api/page/bulk-add-content
254Content-Type: application/json
255 
256{
257  "page_id": "page-id",
258  "items": [
259    {
260      "content_type": "heading_2",
261      "content": "Section Title"
262    },
263    {
264      "content_type": "paragraph",
265      "content": "Paragraph content"
266    },
267    {
268      "content_type": "bookmark",
269      "url": "https://example.com",
270      "content": "External Link"
271    },
272    {
273      "content_type": "link_to_page",
274      "page_reference": "other-page-id",
275      "content": "Internal Link"
276    },
277    {
278      "content_type": "to_do",
279      "content": "Task item",
280      "checked": false
281    }
282  ]
283}
284```
285 
286### 📊 **Analytics**
287 
288```http
289POST /api/analytics
290Content-Type: application/json
291 
292{
293  "type": "workspace"
294}
295```
296 
297**Analytics types:** `workspace`, `content`, `activity`, `database`
298 
299### 🔄 **Bulk Operations** _(OPTIMIZED)_
300 
301```http
302POST /api/bulk
303Content-Type: application/json
304 
305{
306  "operation": "list",
307  "query": "{\"limit\": 10, \"include_block_counts\": false}"
308}
309```
310 
311**Optimization options:**
312 
313- `limit`: Number of pages to process (1-50)
314- `include_block_counts`: Whether to calculate block counts (slower)
315 
316**Operations:** `list`, `analyze`, `create`
317 
318### 🤖 **Agent Integration**
319 
320```http
321POST /api/agent/query
322Content-Type: application/json
323 
324{
325  "action": "search",
326  "parameters": {
327    "query": "search term",
328    "page_size": 10
329  }
330}
331```
332 
333**Available actions:** `search`, `read_page`, `create_page`, `add_content`, `bulk_add_content`, `analytics`, `bulk_operations`
334 
335## 🧪 Testing _(COMPREHENSIVE)_
336 
337Run the comprehensive test suite:
338 
339```bash
340# Start the server first
341python -m notion_mcp_server.api_serverV2
342 
343# In another terminal, run tests
344cd src/notion_mcp_server
345python test_server.py
346```
347 
348**Test Coverage (1,158 lines, 13+ categories):**
349 
350- ✅ **Core Operations**: Health checks, search, page creation/reading
351- ✅ **Content Addition**: All content types including links and bookmarks
352- ✅ **Bulk Content**: Multiple content blocks and optimization
353- ✅ **Link Functionality**: Bookmark and link_to_page validation
354- ✅ **Analytics**: All analytics types and performance
355- ✅ **Bulk Operations**: Optimized pagination and limits
356- ✅ **Agent Integration**: All agent query actions
357- ✅ **Edge Cases**: Error handling, validation, timeouts
358- ✅ **Exception Handling**: Network issues, invalid inputs
359 
360**Test Features:**
361 
362- 🎯 **Detailed Reporting**: Success rates, timing, categorization
363- 📊 **Performance Insights**: Response times and bottlenecks
364- 📄 **JSON Reports**: Exportable test results with timestamps
365- 🧹 **Cleanup Scripts**: Automatic test data management
366 
367## ⚙️ Configuration
368 
369### Environment Variables
370 
371| Variable                 | Default      | Description                   |
372| ------------------------ | ------------ | ----------------------------- |
373| `NOTION_TOKEN`           | _(required)_ | Your Notion integration token |
374| `HOST`                   | `0.0.0.0`    | Server host address           |
375| `PORT`                   | `8081`       | Server port                   |
376| `DEBUG`                  | `false`      | Enable debug mode             |
377| `MAX_PAGE_SIZE`          | `100`        | Maximum results per page      |
378| `DEFAULT_PAGE_SIZE`      | `20`         | Default results per page      |
379| `MAX_CONTENT_LENGTH`     | `2000`       | Maximum content block length  |
380| `ENABLE_ANALYTICS`       | `true`       | Enable analytics endpoints    |
381| `ENABLE_BULK_OPERATIONS` | `true`       | Enable bulk operations        |
382| `LOG_LEVEL`              | `INFO`       | Logging level                 |
383 
384### Configuration Validation
385 
386The server automatically validates all configuration on startup and provides clear error messages for invalid settings.
387 
388## 🔧 Integration Examples
389 
390### With AI Agents
391 
392```python
393import requests
394 
395# Search for content
396response = requests.post("http://localhost:8081/api/agent/query", json={
397    "action": "search",
398    "parameters": {"query": "project notes"}
399})
400 
401# Create a new page with links
402response = requests.post("http://localhost:8081/api/agent/query", json={
403    "action": "create_page",
404    "parameters": {
405        "title": "AI Generated Page",
406        "content": "This page was created by an AI agent"
407    }
408})
409 
410# Add bookmark to page
411response = requests.post("http://localhost:8081/api/agent/query", json={
412    "action": "add_content",
413    "parameters": {
414        "page_id": "page-id",
415        "content_type": "bookmark",
416        "content": "Useful Resource",
417        "url": "https://example.com"
418    }
419})
420```
421 
422### With Your Chatbot
423 
424```python
425# Already integrated in your chatbot_agentic_v3.py!
426# Enhanced with ALL new functions:
427 
428# Core functions
429server.notion_search_content()
430server.notion_read_page()
431server.notion_create_page()
432 
433# Content addition with links
434server.notion_add_paragraph()
435server.notion_add_heading()
436server.notion_add_bullet_point()
437server.notion_add_todo()
438 
439# Smart content helpers
440server.notion_add_structured_content()  # Multi-section content
441server.notion_add_smart_content()       # AI-friendly content parsing
442 
443# Bulk operations
444server.notion_bulk_create_pages()
445server.notion_bulk_list_pages()
446server.notion_bulk_analyze_pages()
447 
448# Analytics
449server.notion_workspace_analytics()
450server.notion_content_analytics()
451server.notion_activity_analytics()
452```
453 
454## 📈 Performance Features _(ENHANCED)_
455 
456- **Async Operations**: Non-blocking I/O for better performance
457- **Smart Timeouts**: Dynamic timeouts (30s standard, 60s bulk, 45s analytics)
458- **Pagination Controls**: Configurable limits to prevent timeouts
459- **Connection Pooling**: Efficient Notion API connections
460- **Request Validation**: Fast input validation and sanitization
461- **Error Recovery**: Graceful handling of API failures
462- **Memory Efficient**: Optimized for low memory usage
463- **Progress Yielding**: Prevents blocking during bulk operations
464 
465## 🛡️ Security & Validation Features _(BULLETPROOF)_
466 
467- **Token Validation**: Automatic Notion token validation
468- **Input Sanitization**: Protection against malicious input
469- **Comprehensive Validation**: All content types validated
470  - Bookmark URLs must be valid HTTP/HTTPS
471  - Page references must exist
472  - Content length limits enforced
473  - Required fields validation
474- **Rate Limiting Ready**: Framework for rate limiting (configurable)
475- **CORS Support**: Secure cross-origin requests
476- **Environment Isolation**: Secure environment variable handling
477- **HTTP Status Handling**: Proper error code processing
478 
479## 📋 Error Handling _(ENHANCED)_
480 
481The server provides detailed error messages for all scenarios:
482 
483### Validation Errors
484 
485- **Missing URLs**: "URL is required for bookmark content type"
486- **Invalid Page References**: "Target page not found: page-name"
487- **Empty Content**: "Content cannot be empty"
488- **Invalid Content Types**: Clear list of supported types
489 
490### API Errors
491 
492- **Invalid Tokens**: Clear guidance for token setup
493- **Missing Pages**: Helpful suggestions for page access
494- **API Limits**: Graceful handling of Notion API limits
495- **Network Issues**: Automatic retry mechanisms
496- **Timeout Prevention**: Smart limits and pagination
497 
498### HTTP Status Codes
499 
500- **200**: Successful operations
501- **400**: Validation errors (missing fields, invalid formats)
502- **404**: Resource not found (pages, invalid references)
503- **500**: Server errors (with detailed diagnostics)
504- **503**: Server not initialized
505 
506## 🆔 Version History
507 
508### V2.1.0 (Current) _(MAJOR UPDATE)_
509 
510- 🔗 **Link Functionality**: Bookmarks and link_to_page support
511- 🛡️ **Bulletproof Validation**: Comprehensive input validation
512- ⚡ **Timeout Optimization**: Fixed bulk operations with smart pagination
513- 🧪 **Enhanced Test Suite**: 48KB comprehensive testing (1,158 lines)
514- 📊 **HTTP Status Handling**: Proper error code processing in tests
515- 🎯 **Performance Controls**: Configurable timeouts and limits
516- 📈 **Smart Content**: AI-friendly content parsing helpers
517 
518### V2.0.0 (Previous)
519 
520- ✅ Complete rewrite with enhanced features
521- ✅ Configuration management system
522- ✅ Basic test suite
523- ✅ Production-ready error handling
524- ✅ Bulk operations support
525- ✅ Enhanced content management
526- ✅ Agent integration endpoints
527 
528### V1.0.0 (Legacy)
529 
530- ✅ Basic MCP server functionality
531- ✅ Core operations (search, read, create)
532- ✅ Simple CLI interface
533 
534## 🤝 Contributing
535 
5361. Fork the repository
5372. Create a feature branch: `git checkout -b feature-name`
5383. Make your changes with tests
5394. Run the comprehensive test suite: `python test_server.py`
5405. Ensure all tests pass (aim for 90%+ success rate)
5416. Submit a pull request
542 
543**Testing Requirements:**
544 
545- All new features must include tests
546- Validation scenarios must be covered
547- Performance implications should be documented
548- Error handling paths must be tested
549 
550## 📞 Support
551 
552If you encounter issues:
553 
5541. **Check Configuration**: Ensure all environment variables are set correctly
5552. **Verify Token**: Make sure your Notion token is valid and has proper permissions
5563. **Run Health Check**: Visit `/health` endpoint to verify server status
5574. **Run Test Suite**: Use `python test_server.py` to identify specific issues
5585. **Check Logs**: Review server logs for detailed error messages
5596. **Test Validation**: Ensure your content meets validation requirements
560 
561**Common Issues:**
562 
563- **Link validation errors**: Ensure URLs start with http/https
564- **Timeout issues**: Use pagination controls for large operations
565- **Page not found**: Verify page sharing with integration
566- **Content too long**: Content blocks limited to 2000 characters
567 
568### 📧 **Contact Information**
569 
570For direct support or questions:
571 
572- **📱 Phone**: +918449035579
573- **📧 Email**: ankitmalik844903@gmail.com
574- **👨‍💻 Developer**: Ankit Malik
575 
576Feel free to reach out for:
577 
578- ✅ Technical support and troubleshooting
579- ✅ Feature requests and suggestions
580- ✅ Integration assistance
581- ✅ Bug reports and issues
582- ✅ Custom development needs
583 
584## 📄 License
585 
586This project is part of the Agentic Long-Term Memory system.
587 
588---
589 
590**🎉 Your Notion MCP Server V2.1 is bulletproof and production-ready!**
591 
592**⚡ New in V2.1:**
593 
594- 🔗 **Link Support** - Bookmarks and internal page links
595- 🛡️ **Bulletproof Validation** - Comprehensive error prevention
596- ⚡ **Timeout Optimization** - Smart pagination and limits
597- 🧪 **48KB Test Suite** - Comprehensive testing and reporting
598- 🎯 **Performance Controls** - Configurable timeouts and limits
599 
600**📊 Quality Metrics:**
601 
602- **1,158 lines** of test coverage
603- **13+ test categories** including edge cases
604- **90%+ success rate** target for all operations
605- **Sub-5 second** response times for optimized operations
606