README.md•3.21 kB
# Notion MCP Server
A Model Context Protocol server for Notion API integration, providing tools to create, retrieve, and update Notion pages.
## Features
- **Create Page**: Create new pages in databases or as child pages
- **Retrieve Page**: Get page properties and metadata
- **Update Page**: Modify page properties, icons, covers, and archive status
- **Retrieve Page Property**: Get detailed property information with pagination support
## Installation
```bash
cd backend/notion-mcp
npm install
```
## Configuration
Create a `.env` file with your Notion API key:
```env
NOTION_API_KEY=your_notion_integration_token_here
NOTION_VERSION=2022-06-28
PORT=3003
```
### Getting a Notion API Key
1. Go to [Notion Developers](https://developers.notion.com/)
2. Create a new integration
3. Copy the "Internal Integration Token"
4. Share your databases/pages with the integration
## Usage
### STDIO Transport (Development)
```bash
npm run dev:stdio
```
### HTTP Transport (Production)
```bash
npm run dev:http
# or
npm start
```
## Available Tools
### notion_create_page
Creates a new page in Notion.
**Parameters:**
- `parent` (required): Parent page or database ID
- `properties` (required): Page properties matching parent schema
- `children` (optional): Page content as block objects
- `icon` (optional): Page icon (emoji or external URL)
- `cover` (optional): Page cover image
**Example:**
```json
{
"parent": {
"type": "database_id",
"database_id": "d9824bdc-8445-4327-be8b-5b47500af6ce"
},
"properties": {
"Name": {
"title": [{"text": {"content": "New Page"}}]
}
},
"icon": {
"type": "emoji",
"emoji": "📝"
}
}
```
### notion_retrieve_page
Retrieves a Notion page by ID.
**Parameters:**
- `page_id` (required): The page ID to retrieve
- `filter_properties` (optional): Specific property IDs to return
### notion_update_page
Updates page properties and metadata.
**Parameters:**
- `page_id` (required): The page ID to update
- `properties` (optional): Properties to update
- `in_trash` (optional): Archive/restore the page
- `icon` (optional): Update page icon
- `cover` (optional): Update page cover
### notion_retrieve_page_property
Retrieves detailed property information with pagination.
**Parameters:**
- `page_id` (required): The page ID
- `property_id` (required): The property ID
- `page_size` (optional): Number of items per page (max 100)
- `start_cursor` (optional): Pagination cursor
## Building
```bash
npm run build
```
## Development
```bash
npm run watch # Watch mode for TypeScript compilation
```
## Client Configuration
For HTTP transport, add to your MCP client config:
```json
{
"mcpServers": {
"notion": {
"url": "http://localhost:3003/mcp"
}
}
}
```
For STDIO transport:
```json
{
"mcpServers": {
"notion": {
"command": "node",
"args": ["./dist/index.js"]
}
}
}
```
## Health Check
When running HTTP transport:
```bash
curl http://localhost:3003/health
```
## Error Handling
The server provides detailed error messages for:
- Missing API keys
- Invalid page/database IDs
- Permission errors
- Malformed requests
- Notion API rate limits
## License
MIT