This MCP server provides a standardized interface to Notion's API, enabling clients to list and query databases, create and update pages, search workspaces, and fetch database details and block children. It leverages an asynchronous HTTP client (httpx) and Pydantic v2 models for type safety and clear error handling, and is compatible with MCP 1.6.0. To use it, first ensure you have a Notion integration API key and run the server in a Python environment. Once running, you can connect via MCP clients (such as Claude Desktop) using the specified server configuration. The server exposes Notion-related endpoints through the MCP protocol, allowing operations like retrieving database schemas, querying pages, and performing create/update actions within your Notion workspace. Configure your client to point at the running MCP server and invoke the available MCP actions as defined by the server’s MCP interface. This setup enables seamless Notion interactions within Claude Desktop and other MCP-compliant clients.

Prerequisites:

• Python 3.9 or newer
• Internet access to install dependencies
• Notion integration token with appropriate read/write permissions

Manual installation steps:

1. Clone the repository: git clone https://github.com/ccabanillas/notion-mcp.git cd notion-mcp

2. Create and activate a virtual environment, then install the package in editable mode: uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e .

   Alternatively, using a standard venv:

   python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -e .

3. Create a .env file in the project root with your Notion API key: NOTION_API_KEY=your_notion_integration_token

4. Run tests (optional): pytest

5. Test running the server: python -m notion_mcp

If you prefer using Smithery for automatic installation, you can follow the Smithery instructions provided in the README, which essentially runs the MCP server via npx install for Claude client compatibility.

Tips and common issues:

• Ensure your Notion API key is correct and the integration has access to the required databases.
• If Claude Desktop isn’t connecting, verify the MCP server is running and that the configured path in claude_desktop_config.json points to the correct Python executable and module.
• The server is designed to be compatible with MCP 1.6.0; if you encounter compatibility warnings, confirm you’re using a supported MCP client version.
• Store the Notion token securely; avoid committing .env files to version control.
• If you need to change Notion permissions, update the integration and re-share databases as needed.