178 lines
3.6 KiB
Markdown
178 lines
3.6 KiB
Markdown
# Notion MCP Server
|
|
|
|
Model Context Protocol (MCP) server for the Notion API. Provides comprehensive access to Notion workspaces including pages, databases, blocks, users, comments, and search.
|
|
|
|
## Features
|
|
|
|
- **Pages**: Create, read, update, and archive pages
|
|
- **Databases**: Query, create, and manage databases with advanced filtering and sorting
|
|
- **Blocks**: Retrieve, append, update, and delete blocks
|
|
- **Users**: Access workspace user information
|
|
- **Comments**: Create and retrieve comments on pages and blocks
|
|
- **Search**: Search across all pages and databases
|
|
- **Rate Limiting**: Built-in rate limiting (3 req/sec) with retry logic
|
|
- **Pagination**: Automatic cursor-based pagination support
|
|
- **Type Safety**: Comprehensive TypeScript types for the entire Notion API
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Set the `NOTION_API_KEY` environment variable:
|
|
|
|
```bash
|
|
export NOTION_API_KEY="your_notion_integration_token"
|
|
```
|
|
|
|
Or create a `.env` file:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env and add your API key
|
|
```
|
|
|
|
### Getting a Notion API Key
|
|
|
|
1. Go to https://www.notion.so/my-integrations
|
|
2. Click "+ New integration"
|
|
3. Give it a name and select the workspace
|
|
4. Copy the "Internal Integration Token"
|
|
5. Share your Notion pages/databases with the integration
|
|
|
|
## Usage
|
|
|
|
### Development
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
### Production
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
### With MCP Client
|
|
|
|
Add to your MCP settings configuration:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"notion": {
|
|
"command": "node",
|
|
"args": ["/path/to/notion/dist/main.js"],
|
|
"env": {
|
|
"NOTION_API_KEY": "your_api_key_here"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Available Tools
|
|
|
|
### Pages
|
|
|
|
- `notion_get_page` - Retrieve a page by ID
|
|
- `notion_create_page` - Create a new page
|
|
- `notion_update_page` - Update page properties or archive
|
|
|
|
### Databases
|
|
|
|
- `notion_get_database` - Get database schema and info
|
|
- `notion_query_database` - Query with filters and sorts
|
|
- `notion_create_database` - Create a new database
|
|
|
|
### Blocks
|
|
|
|
- `notion_get_block` - Get a block by ID
|
|
- `notion_get_block_children` - Get child blocks
|
|
- `notion_append_block_children` - Add blocks to a parent
|
|
- `notion_delete_block` - Archive a block
|
|
|
|
### Users
|
|
|
|
- `notion_get_user` - Get user info
|
|
- `notion_list_users` - List all workspace users
|
|
|
|
### Comments
|
|
|
|
- `notion_create_comment` - Add a comment
|
|
- `notion_list_comments` - Get comments for a block
|
|
|
|
### Search
|
|
|
|
- `notion_search` - Search pages and databases
|
|
|
|
## Architecture
|
|
|
|
### Type System (`src/types/index.ts`)
|
|
|
|
Comprehensive TypeScript definitions including:
|
|
|
|
- All block types as discriminated unions
|
|
- All property types (title, rich_text, number, select, etc.)
|
|
- User, Page, Database, Comment types
|
|
- Filter and Sort builders
|
|
- Pagination types
|
|
- Branded ID types for type safety
|
|
|
|
### Client (`src/clients/notion.ts`)
|
|
|
|
Axios-based HTTP client with:
|
|
|
|
- Bearer token authentication
|
|
- Automatic rate limiting (3 req/sec)
|
|
- Exponential backoff retry logic
|
|
- Cursor-based pagination helpers
|
|
- Async generator support for large datasets
|
|
|
|
### Server (`src/server.ts`)
|
|
|
|
MCP server implementation with:
|
|
|
|
- Lazy-loaded tool handlers
|
|
- Structured error handling
|
|
- JSON schema validation
|
|
- Comprehensive tool definitions
|
|
|
|
### Entry Point (`src/main.ts`)
|
|
|
|
- Environment validation
|
|
- Stdio transport setup
|
|
- Graceful shutdown handling
|
|
- Error logging
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Type check
|
|
npm run typecheck
|
|
|
|
# Build
|
|
npm run build
|
|
|
|
# Run in dev mode
|
|
npm run dev
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Contributing
|
|
|
|
Contributions welcome! Please ensure:
|
|
|
|
- TypeScript compiles with zero errors
|
|
- Follow existing code style
|
|
- Add tests for new features
|
|
- Update documentation
|