{"id":26515415,"url":"https://github.com/awkoy/notion-mcp-server","last_synced_at":"2025-10-13T13:41:12.783Z","repository":{"id":283380645,"uuid":"950937118","full_name":"awkoy/notion-mcp-server","owner":"awkoy","description":"**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.","archived":false,"fork":false,"pushed_at":"2025-04-13T13:02:15.000Z","size":739,"stargazers_count":136,"open_issues_count":1,"forks_count":19,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-10T19:59:51.492Z","etag":null,"topics":["mcp","mcp-server","notion","notion-ai","notion-mcp"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/awkoy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-18T23:06:41.000Z","updated_at":"2025-09-30T12:06:44.000Z","dependencies_parsed_at":"2025-04-13T13:41:24.324Z","dependency_job_id":null,"html_url":"https://github.com/awkoy/notion-mcp-server","commit_stats":null,"previous_names":["awkoy/notion-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/awkoy/notion-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awkoy%2Fnotion-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awkoy%2Fnotion-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awkoy%2Fnotion-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awkoy%2Fnotion-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awkoy","download_url":"https://codeload.github.com/awkoy/notion-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awkoy%2Fnotion-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279015352,"owners_count":26085684,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","notion","notion-ai","notion-mcp"],"created_at":"2025-03-21T06:15:42.246Z","updated_at":"2025-10-13T13:41:12.778Z","avatar_url":"https://github.com/awkoy.png","language":"TypeScript","funding_links":[],"categories":["📚 Projects (1974 total)","Note-Taking and Knowledge Bases","Knowledge \u0026 Memory","🌐 Web Development"],"sub_categories":["MCP Servers","How to Submit"],"readme":"# Notion MCP Server\n\n![License](https://img.shields.io/badge/license-MIT-green)\n![TypeScript](https://img.shields.io/badge/TypeScript-4.9+-blue)\n![Model Context Protocol](https://img.shields.io/badge/MCP-Enabled-purple)\n[![smithery badge](https://smithery.ai/badge/@awkoy/notion-mcp-server)](https://smithery.ai/server/@awkoy/notion-mcp-server)\n![NPM Downloads](https://img.shields.io/npm/dw/notion-mcp-server)\n![Stars](https://img.shields.io/github/stars/awkoy/notion-mcp-server)\n\n**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.\n\n\u003e 🚧 **Active Development**: Database support is now available! Comments and user management tools have been added. 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.\n\n\u003ca href=\"https://glama.ai/mcp/servers/zrh07hteaa\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/zrh07hteaa/badge\" /\u003e\n\u003c/a\u003e\n\n## 📑 Table of Contents\n\n- [Getting Started \u0026 Integration](#-getting-started--integration)\n  - [Setup Process](#setup-process)\n  - [Cursor Integration](#cursor-integration)\n  - [Claude Desktop Integration](#claude-desktop-integration)\n- [Features](#-features)\n- [Documentation](#-documentation)\n  - [Available Tools](#available-tools)\n  - [Available Resources](#available-resources)\n- [Development](#-development)\n- [Technical Details](#-technical-details)\n- [Troubleshooting](#-troubleshooting)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## 🚀 Getting Started \u0026 Integration\n\n### Setup Process\n\n1. **Obtain a Notion API Key**\n   - Create an integration at [Notion Developers](https://www.notion.so/my-integrations)\n   - Copy your API key\n   \n2. **Enable Integration for Your Pages**\n   - Select an existing page or create a new one in Notion\n   - Click the \"...\" menu in the top right corner\n   - Go to \"Connections\" \n   - Find and enable your integration from the list\n   \n   ![Notion Page Connection](page_connection.png)\n\n3. **Choose Your Integration Method**\n   - Follow one of the integration options below based on your preferred MCP client\n\n4. **Ask Your AI Assistant to Interact with Notion**\n   - \"Create a new page with today's tasks\"\n   - \"Update my meeting notes in Notion\"\n   - \"Add bullet points to my meeting notes page\"\n   - \"Create a new database for tracking projects\"\n   - \"Add new entries to my task database\"\n   - \"Add a comment to my project page\"\n   - \"Show me all comments on this document\"\n   - \"List all users in my workspace\"\n   - \"Get information about a specific user\"\n\n### Cursor Integration\n\n#### Method 1: Using mcp.json\n\n1. Create or edit the `.cursor/mcp.json` file in your project directory:\n\n```json\n{\n  \"mcpServers\": {\n    \"notion-mcp-server\": {\n      \"command\": \"env NOTION_TOKEN=YOUR_KEY NOTION_PAGE_ID=YOUR_PAGE_ID npx\",\n      \"args\": [\"-y\", \"notion-mcp-server\"]\n    }\n  }\n}\n```\n\n2. Replace `YOUR_KEY` and `YOUR_PAGE_ID` with your actual Notion API key and page ID\n3. Restart Cursor to apply the changes\n\n#### Method 2: Manual Mode\n\n1. Open Cursor and go to Settings\n2. Navigate to the \"MCP\" or \"Model Context Protocol\" section\n3. Click \"Add Server\" or equivalent\n4. Enter the following command in the appropriate field:\n\n```\nenv NOTION_TOKEN=YOUR_KEY NOTION_PAGE_ID=YOUR_PAGE_ID npx -y notion-mcp-server\n```\n\n5. Replace `YOUR_KEY` and `YOUR_PAGE_ID` with your actual Notion API key and page ID\n6. Save the settings and restart Cursor if necessary\n\n### Claude Desktop Integration\n\n1. Create or edit the `mcp.json` file in your configuration directory:\n\n```json\n{\n  \"mcpServers\": {\n    \"notion-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"notion-mcp-server\"],\n      \"env\": {\n        \"NOTION_TOKEN\": \"YOUR_KEY\",\n        \"NOTION_PAGE_ID\": \"YOUR_PAGE_ID\"\n      }\n    }\n  }\n}\n```\n\n2. Replace `YOUR_KEY` and `YOUR_PAGE_ID` with your actual Notion API key and page ID\n3. Restart Claude Desktop to apply the changes\n\n## 🌟 Features\n\n- **📝 Notion Integration** - Interact with Notion databases, pages, and blocks\n- **🔌 Universal MCP Compatibility** - Works with all MCP clients including Cursor, Claude Desktop, Cline, and Zed\n- **🔍 Data Retrieval** - Fetch information from Notion pages, blocks, and databases\n- **✏️ Content Creation** - Create and update Notion pages and blocks\n- **📊 Block Management** - Append, update, and delete blocks within Notion pages\n- **💾 Database Operations** - Create, query, and update databases\n- **🔄 Batch Operations** - Perform multiple operations in a single request\n- **🗑️ Archive \u0026 Restore** - Archive and restore Notion pages\n- **🔎 Search Functionality** - Search Notion pages and databases by title\n- **💬 Comments Management** - Get, create, and reply to comments on pages and discussions\n- **👥 User Management** - Retrieve workspace users and user information\n\n## 📚 Documentation\n\n### Available Tools\n\nThe server provides the following consolidated tools for interacting with Notion:\n\n#### `notion_pages`\n\nA comprehensive tool for page operations including:\n- Creating new pages with specified content\n- Updating page properties\n- Archiving pages (moving to trash)\n- Restoring previously archived pages\n- Searching for pages by title\n\nExample operations:\n```javascript\n{\n  \"payload\": {\n    \"action\": \"create_page\", // One of: \"create_page\", \"archive_page\", \"restore_page\", \"search_pages\", \"update_page_properties\"\n    \"params\": {\n      // Parameters specific to the chosen action\n    }\n  }\n}\n```\n\n#### `notion_blocks`\n\nA complete toolkit for block operations including:\n- Retrieving block content\n- Fetching child blocks\n- Appending new blocks to a parent\n- Updating existing blocks\n- Deleting blocks\n- Performing batch operations (append, update, delete, mixed)\n\nExample operations:\n```javascript\n{\n  \"payload\": {\n    \"action\": \"append_block_children\", // One of: \"append_block_children\", \"retrieve_block\", \"retrieve_block_children\", \"update_block\", \"delete_block\", \"batch_append_block_children\", \"batch_update_blocks\", \"batch_delete_blocks\", \"batch_mixed_operations\"\n    \"params\": {\n      // Parameters specific to the chosen action\n    }\n  }\n}\n```\n\n#### `notion_database`\n\nA powerful tool for database interactions including:\n- Creating new databases with custom properties\n- Querying databases with filters and sorting\n- Updating database structure and properties\n\nExample operations:\n```javascript\n{\n  \"payload\": {\n    \"action\": \"create_database\", // One of: \"create_database\", \"query_database\", \"update_database\"\n    \"params\": {\n      // Parameters specific to the chosen action\n    }\n  }\n}\n```\n\n#### `notion_comments`\n\nA tool for managing comments on Notion content:\n- Retrieving comments from pages and blocks\n- Adding new comments to pages\n- Replying to existing discussions\n\nExample operations:\n```javascript\n{\n  \"payload\": {\n    \"action\": \"get_comments\", // One of: \"get_comments\", \"add_page_comment\", \"add_discussion_comment\"\n    \"params\": {\n      // Parameters specific to the chosen action\n    }\n  }\n}\n```\n\n#### `notion_users`\n\nA tool for accessing user information:\n- Listing all workspace users\n- Getting details about specific users\n- Retrieving information about the current bot user\n\nExample operations:\n```javascript\n{\n  \"payload\": {\n    \"action\": \"list_users\", // One of: \"list_users\", \"get_user\", \"get_bot_user\"\n    \"params\": {\n      // Parameters specific to the chosen action\n    }\n  }\n}\n```\n\n### Available Resources\n\nThe server currently does not expose any resources, focusing instead on tool-based operations.\n\n## 🛠 Development\n\n1. **Clone the Repository**\n   ```\n   git clone https://github.com/awkoy/notion-mcp-server.git\n   cd notion-mcp-server\n   ```\n\n2. **Install Dependencies**\n   ```\n   npm install\n   ```\n\n3. **Set Up Environment Variables**\n   - Create a `.env` file with:\n     ```\n     NOTION_TOKEN=your_notion_api_key\n     NOTION_PAGE_ID=your_notion_page_id\n     ```\n\n4. **Build the Project**\n   ```\n   npm run build\n   ```\n\n5. **Run the Inspector**\n   ```\n   npm run inspector\n   ```\n\n## 🔧 Technical Details\n\n- Built using TypeScript and the MCP SDK (version 1.7.0+)\n- Uses the official Notion API client (@notionhq/client v2.3.0+)\n- Follows the Model Context Protocol specification\n- Implements tools for CRUD operations on Notion pages, blocks, and databases\n- Supports efficient batch operations for performance optimization\n- Validates input/output with Zod schemas\n\n## ❓ Troubleshooting\n\n- **Common Issues**\n  - **Authentication Errors**: Ensure your Notion token has the correct permissions and integration is enabled for your pages/databases\n  - **Page Access Issues**: Make sure your integration has been added to the pages you're attempting to access\n  - **Rate Limiting**: Notion API has rate limits - use batch operations to optimize requests\n\n- **Getting Help**\n  - Create an issue on the [GitHub repository](https://github.com/awkoy/notion-mcp-server/issues)\n  - Check the [Notion API documentation](https://developers.notion.com/reference/intro)\n  - Visit the MCP community channels for assistance\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawkoy%2Fnotion-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawkoy%2Fnotion-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawkoy%2Fnotion-mcp-server/lists"}