{
  "markdown": "# 📝 Notion Expert v3.0.5 Enhanced Edition\n\n> Complete Notion workspace automation via Model Context Protocol (MCP). Works with [Gemini CLI](https://github.com/google-gemini/gemini-cli) and [Qwen Code](https://github.com/QwenLM/qwen-code).\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)\n[![MCP](https://img.shields.io/badge/MCP-Server-purple.svg)](https://modelcontextprotocol.io/)\n[![Version](https://img.shields.io/badge/Version-3.0.5-brightgreen.svg)](https://github.com/andrecrjr/gemini-notion-expert-extension/releases)\n\nTransform your Notion workspace into a powerful automation hub with **46 comprehensive tools**, file processing, database templates, and intelligent monitoring.\n\n---\n\n## ✨ Quick Start (3 Steps)\n\n**For Gemini/Qwen CLI for extension:**\n```bash\n# 1. Install the extension\ngemini extensions install https://github.com/andrecrjr/gemini-notion-expert-extension --auto-update\n\n# or\n\nqwen extensions install https://github.com/andrecrjr/gemini-notion-expert-extension --auto-update\n\n# 2. Gemini CLI will prompt you for your Notion API key\n# Get your token from: https://www.notion.so/my-integrations\n\n# 3. Verify installation\ngemini mcp list\n```\n\n**For Qwen Code / Gemini if wants only MCP:**\n```bash\n# 1. Register as MCP server\nqwen mcp add notion node \"~/.gemini/extensions/notion-expert/dist/bundle.js\"\n\n# 2. Set environment variable\nexport NOTION_API_KEY=\"ntn_your_token_here\"\n\n# 3. Verify installation\nqwen mcp list\n```\n\n**For direct MCP stdio mode (advanced):**\n```bash\n# Set MCP stdio mode for clean JSON-RPC communication\nexport MCP_STDIO=true\nexport NOTION_API_KEY=\"ntn_your_token_here\"\n\n# Start server directly\nnode dist/bundle.js\n\n# Or with tsx (development)\nMCP_STDIO=true NOTION_API_KEY=\"ntn_xxx\" npx tsx src/server.ts\n```\n\nThat's it! You're ready to use Notion with your AI assistant. 🎉\n\n---\n\n## 📋 Prerequisites\n\n- **Node.js 18+** - [Download here](https://nodejs.org/)\n- **AI CLI Client** - Choose one:\n  - [Gemini CLI](https://github.com/google-gemini/gemini-cli): `npm install -g @google/gemini-cli`\n  - [Qwen Code](https://github.com/QwenLM/qwen-code): Follow installation instructions\n- **Notion Integration Token** - Get yours below 👇\n\n---\n\n## 🔐 Getting Your Notion API Token\n\n1. Go to [Notion Integrations](https://www.notion.so/my-integrations)\n2. Click **\"+ New integration\"**\n3. Configure:\n   - **Name**: `Gemini CLI Extension`\n   - **Associated workspace**: Select your workspace\n   - **Capabilities**: Check all Content, Comment, and User capabilities\n4. Click **\"Submit\"**\n5. Copy the **Internal Integration Token** (starts with `ntn_` or `secret_`)\n\n> ⚠️ **Keep your token secret!** Never share it or commit it to git.\n\n### 🔗 Share Pages with Integration\n\nIn Notion, grant access to pages/databases you want to use:\n1. Open a page or database\n2. Click **\"Share\"** (top right)\n3. Click **\"Add connections\"** or **\"Invite\"**\n4. Select **\"Gemini CLI Extension\"**\n\n---\n\n## ✅ Verify Installation\n\n**Gemini CLI:**\n```bash\n# Check extension is installed\ngemini extensions list\n\n# Check MCP server is connected\ngemini mcp list\n\n# Test with a simple query\necho \"List my Notion databases\" | gemini chat\n```\n\n**Qwen Code:**\n```bash\n# Check MCP server is connected\nqwen mcp list\n\n# Test with a simple query\necho \"List my Notion databases\" | qwen chat\n```\n\n**Expected output:**\n- Extension shows as installed: `✓ notion-expert v3.0.4`\n- MCP server connected: `✓ notion: ... - Connected`\n- Your databases are listed\n\n---\n\n## 🚀 What You Can Do\n\n### Quick Examples\n\n**Gemini CLI:**\n```bash\n# Database operations\necho \"Show me all my Notion databases\" | gemini chat\necho \"Query my Tasks database for incomplete items\" | gemini chat\n\n# Page operations\necho \"Create a meeting notes page titled 'Project Kickoff'\" | gemini chat\necho \"Search for pages about API design\" | gemini chat\n\n# Advanced features\necho \"Create a document scanner database\" | gemini chat\necho \"Check API health status\" | gemini chat\n```\n\n**Qwen Code:**\n```bash\n# Database operations\necho \"Show me all my Notion databases\" | qwen chat\necho \"Query my Tasks database for incomplete items\" | qwen chat\n\n# Page operations\necho \"Create a meeting notes page titled 'Project Kickoff'\" | qwen chat\necho \"Search for pages about API design\" | qwen chat\n\n# Advanced features\necho \"Create a document scanner database\" | qwen chat\necho \"Check API health status\" | qwen chat\n```\n\n### 📊 46 Available Tools\n\n| Category | Tools | Examples |\n|----------|-------|----------|\n| **🔧 Core Notion** | 38 tools | search, create_page, query_database, comments |\n| **📄 File Operations** | 4 tools | upload_file_to_notion, bulk_create_pages_from_files |\n| **🎯 Database Templates** | 1 tool | create_database_from_template (4 templates) |\n| **📊 Health & Analytics** | 2 tools | check_api_health, get_usage_statistics |\n| **🔍 Enhanced Search** | 1 tool | advanced_search (with analytics) |\n\n**Database Templates Available:**\n- **Document Scanner** - Perfect for PDF automation\n- **Project Tracker** - Complete project management\n- **Meeting Notes** - Structured meetings\n- **Task Management** - Task tracking\n\n---\n\n## 🗑️ Uninstallation\n\n```bash\n# Remove MCP server\ngemini mcp remove notion\n\n# Uninstall extension\ngemini extensions uninstall notion-expert\n```\n\n---\n\n## 🔧 Troubleshooting\n\n| Error | Solution |\n|-------|----------|\n| `Tool \"notion_*\" not found` | Register MCP server: `gemini mcp add notion` or `qwen mcp add notion` |\n| `MCP server disconnected` | Check Node.js version (18+) and increase timeout |\n| `Unauthorized` | Verify token is valid and pages are shared |\n| `No databases found` | Share databases with integration in Notion |\n\n### Common Issues\n\n**\"Tool not found\" Errors:**\n```bash\n# Register MCP server manually (Gemini CLI)\ngemini mcp add notion node \"~/.gemini/extensions/notion-expert/dist/bundle.js\" \\\n  -e NOTION_API_KEY=\"${NOTION_API_KEY}\" \\\n  --timeout 30000 \\\n  -s user\n\n# Register MCP server manually (Qwen Code)\nqwen mcp add notion node \"~/.gemini/extensions/notion-expert/dist/bundle.js\" \\\n  -e NOTION_API_KEY=\"${NOTION_API_KEY}\" \\\n  --timeout 30000\n```\n\n**Invalid Token:**\n```bash\n# Test your token\ncurl -H \"Authorization: Bearer $NOTION_API_KEY\" \\\n     -H \"Notion-Version: 2022-06-28\" \\\n     https://api.notion.com/v1/users/me\n```\n\n**Pages Not Accessible:**\n- Open the page in Notion\n- Click **Share** → **Add connections**\n- Select **Gemini CLI Extension**\n\n---\n\n## 📦 Optional: Setup Scripts\n\nFor automated database configuration, run the setup script:\n\n```bash\n# Navigate to extension directory\ncd ~/.gemini/extensions/notion-expert\n\n# Run setup (guides you through database selection/creation)\n# Windows:\n.\\setup-windows.ps1\n\n# macOS/Linux:\nchmod +x setup-unix.sh && ./setup-unix.sh\n```\n\n**What it does:**\n- Discovers your existing databases\n- Auto-detects conversation/project databases\n- Creates databases if needed\n- Stores configuration locally\n\n**Note:** Setup scripts are **optional** - the extension works without them.\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n---\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create feature branch: `git checkout -b feature/amazing-feature`\n3. Commit changes: `git commit -m 'Add amazing feature'`\n4. Push to branch: `git push origin feature/amazing-feature`\n5. Open Pull Request\n\n---\n\n## 🙏 Acknowledgments\n\n- [Gemini CLI](https://github.com/google-gemini/gemini-cli) by Google\n- [Qwen Code](https://github.com/QwenLM/qwen-code) by Alibaba\n- [Notion API](https://developers.notion.com/) by Notion\n- [Model Context Protocol](https://modelcontextprotocol.io/) for MCP server framework\n\n---\n\n## 📚 Complete Tool Reference\n\n### 🔧 Core Notion Operations (38 Tools)\n\n#### Search & Discovery\n- `notion_search` - Search pages and databases by name or content\n- `advanced_search` - Enhanced search with analytics and filtering\n\n#### Page Management\n- `create_page` - Create new pages with markdown content\n- `get_page` - Retrieve page properties and content\n- `update_page` - Modify title, icon, cover, properties\n- `archive_page` - Archive (soft delete) pages\n- `restore_page` - Restore archived pages\n- `duplicate_page` - Copy pages with all content\n\n#### Database Operations\n- `list_databases` - List all accessible databases\n- `get_database` - Get database schema and properties\n- `query_database` - Filter and sort database entries\n- `create_database` - Create new databases with custom schema\n- `update_database` - Modify database properties and schema\n\n#### Block & Content Management\n- `get_page_blocks` - Read page content as structured blocks\n- `append_blocks` - Add content (markdown supported)\n- `update_block` - Modify existing blocks\n- `delete_block` - Remove specific blocks\n\n#### Comments & Collaboration\n- `get_comments` - Read all comments on a page\n- `create_comment` - Add comments to pages\n\n#### Users & Workspace\n- `get_user` - Get current user information\n- `list_users` - List all workspace members\n\n### 🚀 Enhanced Operations (8 Tools)\n\n#### File Processing\n- `upload_file_to_notion` - Upload files with metadata extraction\n- `bulk_create_pages_from_files` - Process multiple files into database entries\n- `start_file_watcher` - Monitor folders for new files\n- `stop_file_watcher` - Stop file monitoring processes\n- `list_active_watchers` - List all active file monitors\n\n#### Database Templates\n- `create_database_from_template` - Create databases with pre-configured schemas\n\n#### Health & Analytics\n- `check_api_health` - Comprehensive API health monitoring\n- `get_usage_statistics` - Detailed API usage analytics\n\n---\n\n## 🔧 Configuration\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `NOTION_API_KEY` | Notion integration token | Yes |\n\nGemini CLI will prompt you for this automatically during first use.\n\n---\n\n## 📁 Project Structure\n\n```\ngemini-notion-expert/\n├── src/\n│   ├── server.ts          # MCP server with all tool handlers\n│   ├── tools.ts            # Tool definitions (JSON Schema)\n│   ├── credentials.ts      # Cross-platform credential retrieval\n│   ├── notion-client.ts    # Notion API wrapper\n│   ├── types/              # TypeScript interfaces\n│   └── managers/           # Business logic managers\n├── dist/                   # Compiled JavaScript (generated)\n├── setup-windows.ps1       # Windows setup script\n├── setup-unix.sh          # macOS/Linux setup script\n├── gemini-extension.json   # Gemini CLI manifest\n├── GEMINI.md              # AI playbook\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n---\n\n**Made with ❤️ for productivity enthusiasts**\n",
  "bytes": 10702,
  "sha": "3e44bd91fa32870cd54b7980644552044d4158b56c4220754b8865828461ad28",
  "repo_slug": "andrecrjr/notion-expert-extension",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_andrecrjr_notion_expert_extension_bb5f1ef2/readme"
}