Notion MCP Server
A Model Context Protocol (MCP) server that provides comprehensive read and write access to Notion workspaces through the Notion API.
Features
- 🔍 Search and retrieve pages, databases, and blocks
- 📝 Create and update pages with rich content
- 🗃️ Database operations - query, create, and update database entries
- 🏗️ Block manipulation - append, update, and delete blocks
- 🔒 Secure authentication using Notion integration tokens
- 🛡️ Error handling with proper MCP error responses
- 📊 Comprehensive logging for debugging and monitoring
Quick Start
1. Installation```bash
git clone https://github.com/your-username/notion-mcp-server.git
cd notion-mcp-server
npm install
### 2. Notion Integration Setup
1. Go to Notion Developers
2. Click "New integration"
3. Fill in basic information:
- Name: "MCP Server Integration"
- Associated workspace: Select your workspace
- Capabilities: Read content, Update content, Insert content
4. Click "Submit"
5. Copy the "Internal Integration Token"
### 3. Configuration
Create a `.env` file in the project root:```env
NOTION_TOKEN=your_notion_integration_token_here
Note: The server automatically finds and loads the .env file from the project directory, regardless of where the MCP client runs it from.
4. Grant Page Access
For each Notion page/database you want to access:
1. Open the page in Notion
2. Click the "..." menu → "Add connections"
3. Select your integration
5. Running the Server```bash
Development
npm run dev
Production
npm start
## Client Integration
### Claude Code (CLI)
Add the server to your Claude Code MCP configuration:```json
{
"mcpServers": {
"notion": {
"command": "node",
"args": ["/path/to/notion-mcp-server/dist/index.js"]
}
}
}
Or using npm:```json
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-p", "/path/to/notion-mcp-server", "node", "dist/index.js"]
}
}
}
The server will automatically read the `NOTION_TOKEN` from your `.env` file.
### Claude Desktop
Add to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json````json
{
"mcpServers": {
"notion": {
"command": "node",
"args": ["/path/to/notion-mcp-server/dist/index.js"]
}
}
}
The server will automatically read the NOTION_TOKEN from your .env file in the project directory.
ChatGPT (via OpenAI)
For ChatGPT integration, you'll need to run the server with a JSON-RPC transport. Create a wrapper script:
notion-mcp-wrapper.js:```javascript
!/usr/bin/env node
const { spawn } = require('child_process');
const server = spawn('node', ['/path/to/notion-mcp-server/dist/index.js'], {
env: process.env, // Inherits environment variables including NOTION_TOKEN from .env
stdio: ['pipe', 'pipe', 'pipe'],
cwd: '/path/to/notion-mcp-server' // Ensures .env file is found
});
process.stdin.pipe(server.stdin);
server.stdout.pipe(process.stdout);
server.stderr.pipe(process.stderr);
server.on('exit', (code) => {
process.exit(code);
});
Then configure ChatGPT to use:```json
{
"tools": [
{
"type": "mcp_server",
"mcp_server": {
"command": "node",
"args": ["/path/to/notion-mcp-wrapper.js"]
}
}
]
}
Alternative: Global Installation
For easier configuration, you can install the server globally:```bash
Make the server globally available
npm link
Or install globally if published
npm install -g notion-mcp-server
Then use in configurations:```json
{
"mcpServers": {
"notion": {
"command": "notion-mcp-server"
}
}
}
Note: When using global installation, ensure your .env file is in the working directory where the client runs, or set the NOTION_TOKEN as a system environment variable.
Security Best Practices
✅ DO: Keep your Notion token in the .env file```env
NOTION_TOKEN=secret_your_notion_integration_token_here
❌ **DON'T**: Put tokens directly in MCP client configurations```json
// AVOID THIS - tokens exposed in config files
{
"mcpServers": {
"notion": {
"env": {
"NOTION_TOKEN": "secret_token_here"
}
}
}
}
System Environment Variables (Optional)
If you prefer system-wide environment variables instead of .env files:```bash
Add to your shell profile (.bashrc, .zshrc, etc.)
export NOTION_TOKEN="your_notion_integration_token_here"
This approach works well with global installations and containerized deployments.
## MCP Tools Available
### Page Operations
#### `notion_search_pages`
Search for pages across your workspace.```json
{
"query": "meeting notes",
"filter": "page",
"sort": "last_edited_time"
}
notion_get_page
Retrieve a specific page with all its content.```json
{
"page_id": "page-uuid-here"
}
#### `notion_create_page`
Create a new page with content.```json
{
"parent": {
"type": "page_id",
"page_id": "parent-page-uuid"
},
"title": "New Page Title",
"content": "# Heading\n\nThis is some content."
}
notion_update_page
Update an existing page's properties and content.```json
{
"page_id": "page-uuid-here",
"title": "Updated Title",
"content": "Updated content here"
}
#### `notion_append_blocks`
Append blocks to an existing page.```json
{
"block_id": "page-or-block-uuid",
"content": "Additional content to append"
}
Database Operations
notion_query_database
Query a database with filters and sorting.```json
{
"database_id": "database-uuid-here",
"filter": {
"property": "Status",
"select": {
"equals": "In Progress"
}
},
"sorts": [
{
"property": "Created",
"direction": "descending"
}
]
}
#### `notion_create_database_page`
Create a new page in a database.```json
{
"database_id": "database-uuid-here",
"properties": {
"Name": {
"title": [
{
"text": {
"content": "New Task"
}
}
]
},
"Status": {
"select": {
"name": "To Do"
}
}
},
"content": "Task description here"
}
notion_update_database_page
Update properties of a database page.```json
{
"page_id": "page-uuid-here",
"properties": {
"Status": {
"select": {
"name": "Completed"
}
}
}
}
### Block Operations
#### `notion_get_blocks`
Get child blocks of a page or block.```json
{
"block_id": "block-uuid-here"
}
notion_update_block
Update a specific block's content.```json
{
"block_id": "block-uuid-here",
"content": "Updated block content"
}
#### `notion_delete_block`
Delete a specific block.```json
{
"block_id": "block-uuid-here"
}
Utility Operations
notion_get_users
List all users in the workspace.
notion_get_databases
List accessible databases.
Configuration
Environment Variables
| Variable | Description | Required |
|---|---|---|
NOTION_TOKEN |
Notion integration token | Yes |
LOG_LEVEL |
Logging level (debug, info, warn, error) | No (default: info) |
PORT |
Server port for health checks | No (default: 3000) |
Integration Capabilities
When creating your Notion integration, ensure you enable:
- ✅ Read content - Required for all read operations
- ✅ Update content - Required for updating pages/blocks
- ✅ Insert content - Required for creating pages/blocks
- ✅ Read user information - Required for user operations
Error Handling
The server implements comprehensive error handling:
- Authentication errors - Invalid or missing Notion token
- Permission errors - Access denied to specific pages/databases
- Rate limiting - Automatic retry with exponential backoff
- Validation errors - Invalid parameters or malformed requests
- Network errors - Connection timeouts and retries
Development
Project Structure```
notion-mcp-server/
├── src/
│ ├── index.ts # Main server entry point
│ ├── types.ts # TypeScript type definitions
│ ├── tools/ # MCP tool implementations
│ │ ├── pages.ts # Page-related tools
│ │ ├── databases.ts # Database-related tools
│ │ ├── blocks.ts # Block-related tools
│ │ └── utils.ts # Utility tools
│ ├── notion/ # Notion API wrappers
│ │ ├── client.ts # Notion client setup
│ │ ├── converters.ts # Content converters
│ │ └── validators.ts # Input validation
│ └── utils/
│ ├── logger.ts # Logging utilities
│ └── errors.ts # Error handling
├── tests/ # Test files
├── docs/ # Additional documentation
├── package.json
├── tsconfig.json
├── .env.example
└── README.md
### Building```bash
npm run build
Testing```bash
Run all tests
npm test
Run tests with coverage
npm run test:coverage
Run integration tests (requires valid Notion token)
npm run test:integration
### Linting```bash
npm run lint
npm run lint:fix
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
Development Guidelines
- Follow TypeScript best practices
- Add tests for new features
- Update documentation for API changes
- Use conventional commit messages
- Ensure all tests pass before submitting PR
Security
- Never commit
.envfiles or tokens to the repository - Use environment variables for sensitive configuration
- Regularly rotate your Notion integration tokens
- Follow the principle of least privilege when granting access
Troubleshooting
Common Issues
"Cannot use import statement outside a module" Error
This project uses ES modules. Make sure your package.json includes:```json
{
"type": "module"
}
#### "Expected ',' or ']' after array element in JSON" Error
This error occurs when logs are sent to stdout instead of stderr, interfering with MCP JSON communication. The server has been fixed to send all logs to stderr, but if you encounter this:
1. Ensure you're using the latest version
2. Check that no `console.log` statements are in the code
3. Restart Claude Desktop after updating the server
#### "Missing required environment variable: NOTION_TOKEN" Error
The server automatically loads the `.env` file from the project directory. If you see this error:
1. Ensure the `.env` file exists in the project root with your token:```env
NOTION_TOKEN=your_notion_integration_token_here
```
2. Verify the token is valid and not expired
3. Check that there are no extra spaces or quotes around the token
#### "Cannot find module" Error
- Verify the path in your MCP client configuration points to the correct location
- Ensure you've built the project: `npm run build`
- Check that the `dist/` folder exists and contains `index.js`
#### "Unauthorized" Error
- Verify your `NOTION_TOKEN` is correct in the `.env` file
- Ensure the integration has been added to the pages/databases you're accessing
- Check that your integration has the required capabilities
#### "Object not found" Error
- Verify the page/database ID is correct
- Ensure the integration has access to the specific object
- Check if the object has been deleted or moved
#### Rate Limiting
- The server automatically handles rate limits with exponential backoff
- If you encounter persistent rate limiting, consider reducing request frequency
### Debug Mode
Enable debug logging:```bash
LOG_LEVEL=debug npm start
This will output detailed information about API calls and responses.
Testing the Server
To verify the server works correctly:```bash
Build the project
npm run build
Test TypeScript compilation
npm run typecheck
Run the server (will start and wait for MCP connections)
npm start
```
Changelog
See CHANGELOG.md for a detailed list of changes.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Notion API for providing the excellent API
- Model Context Protocol for the MCP specification
- The open-source community for inspiration and contributions
Support
- 📖 Documentation
- 🐛 Issue Tracker
- 💬 Discussions
- 📧 Email Support
Made with ❤️ by the open-source community
