Improved Notion MCP Server

An enhanced Notion MCP server with better markdown conversion and composite tools for AI agents.

Features

• Token Optimization - All read operations return markdown instead of raw JSON (~80% token reduction)
• Composite Tools - Batch operations, append content, create pages with content in one call
• Full Notion API Coverage - Search, CRUD operations, database queries, user listing
• TypeScript - Full type safety and modern tooling

Installation

npm install improved-notion-mcp

Configuration

Set your Notion API token:

export NOTION_TOKEN=your_notion_integration_token

Or use NOTION_API_KEY as an alternative.

Usage

CLI

npx improved-notion-mcp

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "improved-notion-mcp": {
      "command": "npx",
      "args": ["-y", "improved-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "your_token_here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "improved-notion-mcp": {
      "command": "npx",
      "args": ["-y", "improved-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "your_token_here"
      }
    }
  }
}

Tools

Search & Discovery

• notion_search - Search pages and databases
• notion_list_databases - List all accessible databases
• notion_list_users - List workspace users

Read Operations (Token-Optimized)

• notion_get_page - Get page content as markdown (~80% fewer tokens)
• notion_get_database_schema - Get database schema/properties
• notion_query_database - Query database with filters

Write Operations

• notion_create_page - Create a new page (optionally with content)
• notion_create_database_entry - Create database entry
• notion_update_page - Update page properties or content
• notion_append_content - Append markdown to existing page

Batch Operations

• notion_batch_create - Create multiple pages at once

Delete Operations

• notion_delete_page - Archive a page

Token Optimization

The official Notion MCP returns raw JSON from the API, which includes lots of metadata that AI agents don't need. This server:

1. Converts all page content to markdown
2. Formats properties as readable key-value pairs
3. Strips unnecessary metadata

Result: ~80% reduction in token usage for typical operations.

Comparison

| Feature | Official Notion MCP | This Server | |---------|-------------------|-------------| | Token usage | High (raw JSON) | Low (markdown) | | Composite tools | Limited | Batch create, append | | Block types | 15 | 20+ | | Tools | ~20 auto-generated | 12 focused |

Development

npm run dev    # Development mode
npm run build  # Build for production
npm start      # Run production build

License

MIT