Skip to content
Back to search

notion-mcp

A Model Context Protocol (MCP) server implementation for Notion integration, providing a standardized interface for interacting with Notion's API.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ccabanillas--notion-mcp/badge.svg)](/listings/ccabanillas--notion-mcp)

HTML

<a href="/listings/ccabanillas--notion-mcp"><img src="/api/listings/ccabanillas--notion-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installing via Smithery

To install Notion Integration Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@ccabanillas/notion-mcp):

npx -y @smithery/cli install @ccabanillas/notion-mcp --client claude

Manual Installation

1. Clone the repository:

git clone https://github.com/ccabanillas/notion-mcp.git
cd notion-mcp

2. Create a virtual environment and install dependencies (using uv):

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

Alternatively, using 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:

NOTION_API_KEY=your_notion_integration_token

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 143 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Notion MCP Server
  2. [![smithery badge](https://smithery.ai/badge/@ccabanillas/notion-mcp)](https://smithery.ai/server/@ccabanillas/notion-mcp)
  3. 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.
  4. ## Features
  5. - List and query Notion databases
  6. - Create and update pages
  7. - Search across Notion workspace
  8. - Get database details and block children
  9. - Full async/await support with httpx
  10. - Type-safe with Pydantic v2 models
  11. - Proper error handling with detailed logging
  12. - Compatibility with MCP 1.6.0
  13. ## Installation
  14. ### Installing via Smithery
  15. To install Notion Integration Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@ccabanillas/notion-mcp):
  16. ```bash
  17. npx -y @smithery/cli install @ccabanillas/notion-mcp --client claude
  18. ```
  19. ### Manual Installation
  20. 1. Clone the repository:
  21. ```bash
  22. git clone https://github.com/ccabanillas/notion-mcp.git
  23. cd notion-mcp
  24. ```
  25. 2. Create a virtual environment and install dependencies (using uv):
  26. ```bash
  27. uv venv
  28. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  29. uv pip install -e .
  30. ```
  31. Alternatively, using standard venv:
  32. ```bash
  33. python -m venv venv
  34. source venv/bin/activate # On Windows: venv\Scripts\activate
  35. pip install -e .
  36. ```
  37. 3. Create a `.env` file in the project root:
  38. ```bash
  39. NOTION_API_KEY=your_notion_integration_token
  40. ```
  41. ## Usage
  42. 1. Test the server (it should run without errors):
  43. ```bash
  44. python -m notion_mcp
  45. ```
  46. 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):
  47. ```json
  48. {
  49. "servers": {
  50. "notion-mcp": {
  51. "command": "/Users/username/Projects/notion-mcp/.venv/bin/python",
  52. "args": ["-m", "notion_mcp"],
  53. "cwd": "/Users/username/Projects/notion-mcp"
  54. }
  55. }
  56. }
  57. ```
  58. Be sure to replace `/Users/username/` with your actual home directory path.
  59. ## Development
  60. ### Project Structure
  61. ```
  62. notion-mcp/
  63. ├── src/
  64. │ └── notion_mcp/
  65. │ ├── models/
  66. │ │ ├── __init__.py
  67. │ │ └── notion.py # Pydantic models for Notion objects
  68. │ ├── __init__.py
  69. │ ├── __main__.py # Entry point
  70. │ ├── client.py # Notion API client
  71. │ └── server.py # MCP server implementation
  72. ├── .env # Environment variables (add your Notion API key here)
  73. ├── .gitignore
  74. ├── pyproject.toml # Project dependencies
  75. └── README.md
  76. ```
  77. ### Running Tests
  78. ```bash
  79. pytest
  80. ```
  81. ## Configuration
  82. The server requires a Notion integration token. To set this up:
  83. 1. Go to https://www.notion.so/my-integrations
  84. 2. Create a new integration with appropriate capabilities (read/write as needed)
  85. 3. Copy the integration token
  86. 4. Add it to your `.env` file in the project root directory:
  87. ```
  88. NOTION_API_KEY=your_notion_integration_token
  89. ```
  90. 5. Share your Notion databases with the integration (from the database's "Share" menu)
  91. ## Contributing
  92. 1. Fork the repository
  93. 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
  94. 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
  95. 4. Push to the branch (`git push origin feature/amazing-feature`)
  96. 5. Open a Pull Request
  97. ## License
  98. MIT License - Use at your own risk
  99. ## Troubleshooting
  100. ### Common Issues
  101. - **Connection Errors**: Make sure your Notion API key is correct and you have internet access
  102. - **Permission Errors**: Ensure your integration has been given access to the databases you're trying to access
  103. - **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
  104. ## Acknowledgments
  105. - Built to work with Claude Desktop and other MCP clients
  106. - Uses Notion's API (latest compatible version 2022-02-22)
  107. - MCP 1.6.0 compatibility maintained
  108. - Special thanks to [danhilse](https://github.com/danhilse), I referenced his [notion-mcp-server](https://github.com/danhilse/notion-mcp-server) project

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.