Notion MCP Server

# MCP Server Rules for Cursor AI ## Overview This rules file defines how Cursor AI should interact with the Model Context Protocol (MCP) server for Notion. These rules help Cursor AI understand the capabilities and limitations of the Notion MCP server. ## Server Information - **Name**: Notion MCP Server - **Purpose**: Provides access to Notion workspaces via the Model Context Protocol - **Transport**: stdio (standard input/output) - **Authentication**: Requires a Notion API key provided via command-line parameter `--api-key` or stored in environment variable `NOTION_API_KEY` - **Installation**: Run directly via `npx @ecovirtual/mcp-server-notion@latest -y --api-key=your_notion_api_key` ## Command Format Best Practices - Always use the `@latest` tag to ensure you're using the most recent version - Include the `-y` flag to skip confirmation prompts - When using the `--api-key` parameter, use the format `--api-key=your_notion_api_key` (with equals sign, no spaces) - When using environment variables, set `NOTION_API_KEY` (not `--api-key`) - On Windows, prefix with `cmd /c` to ensure proper execution: `cmd /c npx @ecovirtual/mcp-server-notion@latest -y --api-key=your_notion_api_key` - On macOS/Linux, consider using the full path to npx if you encounter issues - For troubleshooting "Failed to create client" errors, try creating a shell script wrapper ## Available Tools ### Search Tools - `search`: Search for pages or databases in a Notion workspace - Parameters: `query` (string), `filter_object_type` (string), `page_size` (number) ### Database Tools - `query-database`: Query a Notion database with optional filters and sorting - Parameters: `database_id` (string), `filter` (string), `sorts` (string), `page_size` (number), `start_cursor` (string) - `get-database`: Retrieve a Notion database by ID - Parameters: `database_id` (string) ### Page Tools - `create-page`: Create a new page in Notion - Parameters: `parent_type` (string), `parent_id` (string), `properties` (string), `children` (string) - `get-page`: Retrieve a Notion page by ID - Parameters: `page_id` (string) - `update-page`: Update a Notion page - Parameters: `page_id` (string), `properties` (string), `archived` (boolean) ### Block Tools - `append-blocks`: Add content blocks to a page or block - Parameters: `block_id` (string), `children` (string) - `get-block`: Retrieve a block by ID - Parameters: `block_id` (string) - `get-block-children`: Retrieve children blocks of a block or page - Parameters: `block_id` (string), `page_size` (number), `start_cursor` (string) - `update-block`: Update a block - Parameters: `block_id` (string), `properties` (string) - `delete-block`: Delete (archive) a block - Parameters: `block_id` (string) ## Usage Patterns ### Natural Language Queries When the user asks about Notion content, use the `search` tool first to find relevant pages or databases. Example: ``` User: Find my notes about project planning Action: Use the search tool with query="project planning" ``` ### Database Operations When working with databases, first get the database structure with `get-database`, then query it with `query-database`. Example: ``` User: Show me all tasks with status "In Progress" Action: 1. Use search to find the tasks database 2. Use get-database to understand its structure 3. Use query-database with appropriate filters ``` ### Content Creation For creating content, use `create-page` for new pages and `append-blocks` for adding content to existing pages. Example: ``` User: Create a new page with today's meeting notes Action: Use create-page with appropriate properties and children blocks ``` ## Response Handling - All responses are JSON strings that should be parsed before presenting to the user - Large responses should be summarized or formatted for better readability - Error responses include an `isError` flag and should be presented clearly to the user ## Error Handling - Authentication errors: Prompt the user to check their Notion API key - Permission errors: Suggest sharing the relevant pages/databases with the integration - Rate limiting: Inform the user and suggest trying again later - Invalid parameters: Provide clear guidance on the correct parameter format ## Limitations - The server cannot access pages/databases that haven't been shared with the integration - Complex Notion features like comments and user mentions may have limited support - Rate limits from the Notion API apply (approximately 3 requests per second) - The server doesn't maintain state between requests ## Best Practices - Use IDs consistently: Always use the same ID format (UUID without hyphens) - Minimize requests: Combine operations when possible to reduce API calls - Handle pagination: For large datasets, use pagination parameters - Format JSON: When showing JSON to users, format it for readability - Validate input: Ensure parameters match the expected format before sending