NotionMCP Light

NotionMCP Light

NotionMCP Lightは、Notion APIを使用してMarkdownファイルとNotionページを同期するModel Context Protocol (MCP)サーバーです。

概要

このプロジェクトは、Notionの公式Model Context Protocol (MCP)サーバーが抱える非効率性（Markdownをブロック単位で読み書きし、LLMトークンを消費する点）を解決するために開発されました。トークンを使用せず、API経由で直接MarkdownファイルとNotionのページ／データベースを同期できる非公式のMCPサーバーを提供します。

機能

• Markdown → Notion

  • H1をページタイトルとして認識
  • Markdownの内容をNotionページまたはデータベースのページとして作成
  • データベースIDを指定可能
  • Notion APIを直接使用（トークン未使用）

• Notion → Markdown

  • 指定されたページまたはデータベースのページをMarkdown形式に変換
  • タイトルをH1として出力
  • ブロック構造をMarkdownに変換
  • ファイルに保存

• MCPサーバー対応

  • Model Context Protocol（MCP）に準拠
  • CursorやClineなどのAIツールから呼び出し可能なエンドポイントを提供
  • JSON-RPC over stdioベースで動作

インストール

依存関係のインストール

# uvがインストールされていない場合は先にインストール
# pip install uv

# 依存関係のインストール
uv sync

Notion API Tokenの設定

1. Notion Developersでアカウントを作成し、APIトークンを取得します。
2. 環境変数に設定するか、.envファイルを作成してトークンを設定します。

# .envファイルの例
NOTION_TOKEN=your_notion_api_token

使い方

MCPサーバーの起動

uvを使用する場合（推奨）

uv run python -m src.main

または、トークンを直接指定する場合：

uv run python -m src.main --token your_notion_api_token

通常のPythonを使用する場合

python -m src.main

または、トークンを直接指定する場合：

python -m src.main --token your_notion_api_token

Cline/Cursorでの設定

Cline/Cursor/Claude CodeなどのAIコーディングツールでNotionMCP Lightを使用するには、各ツールのMCPサーバ設定を行うJSONファイルに以下のような設定を追加します：

{
  "mcpServers": {
    "notion-mcp-light": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/notion-mcp-light",
        "-m",
        "src.main"
      ],
      "env": {
        "NOTION_TOKEN": "your_notion_api_token"
      }
    }
  }
}

/path/to/notion-mcp-lightは、NotionMCP Lightのインストールディレクトリ、your_notion_api_tokenは、NotionのAPIトークンに置き換えてください。

MCPツールの使用方法

NotionMCP Lightは以下のMCPツールを提供します：

uploadMarkdown

Markdownファイルをアップロードし、Notionページとして作成します。

{
  "jsonrpc": "2.0",
  "method": "uploadMarkdown",
  "params": {
    "filepath": "path/to/markdown.md",
    "database_id": "optional_database_id",
    "page_id": "optional_parent_page_id"
  },
  "id": 1
}

downloadMarkdown

NotionページをダウンロードしてMarkdownファイルとして保存します。

{
  "jsonrpc": "2.0",
  "method": "downloadMarkdown",
  "params": {
    "page_id": "notion_page_id",
    "output_path": "path/to/output.md"
  },
  "id": 2
}

ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細はLICENSEファイルを参照してください。