camoneart/notion-tag-migrate-mcp

Notion Tag Migrate MCP

A Model Context Protocol (MCP) server for migrating Notion database tags from multiple multi-select columns to unified Category and Tag columns.

🎯 Purpose

This MCP server helps migrate existing Notion databases with scattered multi-select tag columns into a clean, unified tagging system with:

• Category: Single-select column for primary classification
• Tag: Multi-select column for all consolidated tags

Perfect for organizing long-running databases like "Second Brain" systems with 3-4 years of accumulated data.

🚀 Quick Start

Prerequisites

• Node.js 18+
• A Notion integration token
• Database ID to migrate

Installation

# Install dependencies
pnpm install

# Copy environment template
cp .env.example .env

# Edit .env with your Notion token and database ID
# Then build the project
pnpm build

Configuration

Edit .env with your settings:

NOTION_TOKEN=secret_your_notion_integration_token
DATABASE_ID=your-database-id-here

🛠️ MCP Tools

This server provides 5 main tools:

1. analyze_database

Analyzes your database structure and provides migration recommendations.

{
  database_id: string,
  notion_token?: string  // optional if set in env
}

2. dry_run

Previews migration changes without executing them.

{
  database_id: string,
  notion_token?: string,
  limit?: number,        // max pages to analyze (default: 10)
  config_path?: string   // custom config file
}

3. migrate_pages

Executes the actual migration.

{
  database_id: string,
  notion_token?: string,
  batch_size?: number,   // pages per batch (default: 10)
  limit?: number,        // max pages to migrate
  from_page_id?: string, // resume from specific page
  dry_run?: boolean      // preview mode
}

4. get_progress

Checks current migration progress.

{
  migration_id?: string  // optional migration ID
}

5. backup_database

Creates backup before migration.

{
  database_id: string,
  notion_token?: string,
  format?: "json" | "csv" | "both"  // default: json
}

📋 Migration Workflow

1. Analyze: analyze_database to understand your data
2. Backup: backup_database for safety
3. Preview: dry_run to see proposed changes
4. Migrate: migrate_pages to execute
5. Monitor: get_progress to track status

Example Usage with Claude Code

# Analyze database structure
mcp__notion-tag-migrate__analyze_database database_id="your-db-id"

# Create backup
mcp__notion-tag-migrate__backup_database database_id="your-db-id" format="both"

# Preview changes (first 10 pages)
mcp__notion-tag-migrate__dry_run database_id="your-db-id" limit=10

# Execute migration
mcp__notion-tag-migrate__migrate_pages database_id="your-db-id" batch_size=5

# Check progress
mcp__notion-tag-migrate__get_progress

⚙️ Configuration

Default Column Mapping

OLD_MULTI_SELECT_COLUMNS = [
  "AI labels", "MCP labels", "AI Agents",
  "Site labels", "Web Dev labels", "Brand labels"
]
CATEGORY_SOURCE_COLUMNS = ["Category", "カテゴリ"]
NEW_CATEGORY_COLUMN = "Category"
NEW_TAG_COLUMN = "Tag"

Safety Features

• Tag Normalization: Removes duplicates, normalizes spacing, handles full-width characters
• Rate Limiting: Built-in delays and retry logic
• Resume Support: Continue from where migration left off
• Progress Tracking: Real-time status and error reporting
• Backup Integration: Automatic data preservation

📊 Reports & Outputs

All outputs are saved to:

• ./reports/: Dry-run reports and migration summaries (JSON/CSV)
• ./backups/: Database backups (JSON/CSV)
• ./logs/: Migration logs
• ./migration-state/: Progress tracking

🔧 Development

# Development mode
pnpm dev

# Build
pnpm build

# Lint
pnpm lint

# Type check
pnpm typecheck

📝 License

MIT

🤝 Contributing

Issues and PRs welcome at GitHub Repository

Built with ❤️ for Notion power users managing complex knowledge bases.