# Notion MCP Server
[](https://smithery.ai/server/@ccabanillas/notion-mcp)
A Model Context Protocol (MCP) server implementation for Notion integration, providing a standardized interface for interacting with Notion's API. Compatible with Claude Desktop and other MCP clients.
## Features
- List and query Notion databases
- Create and update pages
- Search across Notion workspace
- Get database details and block children
- Full async/await support with httpx
- Type-safe with Pydantic v2 models
- Proper error handling with detailed logging
- Compatibility with MCP 1.6.0
## Installation
### Installing via Smithery
To install Notion Integration Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@ccabanillas/notion-mcp):
```bash
npx -y @smithery/cli install @ccabanillas/notion-mcp --client claude
```
### Manual Installation
1. Clone the repository:
```bash
git clone https://github.com/ccabanillas/notion-mcp.git
cd notion-mcp
```
2. Create a virtual environment and install dependencies (using uv):
```bash
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e .
```
Alternatively, using standard venv:
```bash
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:
```bash
NOTION_API_KEY=your_notion_integration_token
```
## Usage
1. Test the server (it should run without errors):
```bash
python -m notion_mcp
```
2. To use it with Claude Desktop, adjust your `claude_desktop_config.json` file (located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"servers": {
"notion-mcp": {
"command": "/Users/username/Projects/notion-mcp/.venv/bin/python",
"args": ["-m", "notion_mcp"],
"cwd": "/Users/username/Projects/notion-mcp"
}
}
}
```
Be sure to replace `/Users/username/` with your actual home directory path.
## Development
### Project Structure
```
notion-mcp/
├── src/
│ └── notion_mcp/
│ ├── models/
│ │ ├── __init__.py
│ │ └── notion.py # Pydantic models for Notion objects
│ ├── __init__.py
│ ├── __main__.py # Entry point
│ ├── client.py # Notion API client
│ └── server.py # MCP server implementation
├── .env # Environment variables (add your Notion API key here)
├── .gitignore
├── pyproject.toml # Project dependencies
└── README.md
```
### Running Tests
```bash
pytest
```
## Configuration
The server requires a Notion integration token. To set this up:
1. Go to https://www.notion.so/my-integrations
2. Create a new integration with appropriate capabilities (read/write as needed)
3. Copy the integration token
4. Add it to your `.env` file in the project root directory:
```
NOTION_API_KEY=your_notion_integration_token
```
5. Share your Notion databases with the integration (from the database's "Share" menu)
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
MIT License - Use at your own risk
## Troubleshooting
### Common Issues
- **Connection Errors**: Make sure your Notion API key is correct and you have internet access
- **Permission Errors**: Ensure your integration has been given access to the databases you're trying to access
- **Claude Desktop Integration**: If Claude Desktop isn't connecting, check that your config path is correct and that the server is running without logging to stdout
## Acknowledgments
- Built to work with Claude Desktop and other MCP clients
- Uses Notion's API (latest compatible version 2022-02-22)
- MCP 1.6.0 compatibility maintained
- Special thanks to [danhilse](https://github.com/danhilse), I referenced his [notion-mcp-server](https://github.com/danhilse/notion-mcp-server) project