ldraney-notion-mcp 0.1.1__py3-none-any.whl

ldraney_notion_mcp-0.1.1.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: ldraney-notion-mcp
+Version: 0.1.1
+Summary: MCP server wrapping the Notion Python SDK (v2025-09-03)
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0
+Requires-Dist: ldraney-notion-sdk>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# notion-mcp
+
+MCP (Model Context Protocol) server that wraps [`ldraney/notion-sdk`](https://github.com/ldraney/notion-sdk) — a Python SDK for the Notion API v2025-09-03.
+
+## Overview
+
+This project exposes the full Notion Python SDK as MCP tools, allowing AI assistants (Claude, etc.) to interact with Notion workspaces through a standardized tool interface.
+
+## SDK Coverage
+
+Every method in `notion-sdk` maps to an MCP tool, organized by module:
+
+### Pages
+| Tool | SDK Method | Notion Endpoint |
+|---|---|---|
+| `create_page` | `create_page()` | `POST /v1/pages` |
+| `get_page` | `get_page()` | `GET /v1/pages/{id}` |
+| `update_page` | `update_page()` | `PATCH /v1/pages/{id}` |
+| `archive_page` | `archive_page()` | `PATCH /v1/pages/{id}` |
+| `move_page` | `move_page()` | `POST /v1/pages/{id}/move` |
+
+### Databases
+| Tool | SDK Method | Notion Endpoint |
+|---|---|---|
+| `create_database` | `create_database()` | `POST /v1/databases` |
+| `get_database` | `get_database()` | `GET /v1/databases/{id}` |
+| `update_database` | `update_database()` | `PATCH /v1/databases/{id}` |
+| `archive_database` | `archive_database()` | `PATCH /v1/databases/{id}` |
+| `query_database` | `query_database()` | auto-resolves data source, then `POST /v1/data_sources/{id}/query` |
+
+### Data Sources
+| Tool | SDK Method | Notion Endpoint |
+|---|---|---|
+| `get_data_source` | `get_data_source()` | `GET /v1/data_sources/{id}` |
+| `update_data_source` | `update_data_source()` | `PATCH /v1/data_sources/{id}` |
+| `query_data_source` | `query_data_source()` | `POST /v1/data_sources/{id}/query` |
+| `list_data_source_templates` | `list_data_source_templates()` | `GET /v1/data_sources/{id}/templates` |
+
+### Blocks
+| Tool | SDK Method | Notion Endpoint |
+|---|---|---|
+| `get_block` | `get_block()` | `GET /v1/blocks/{id}` |
+| `get_block_children` | `get_block_children()` | `GET /v1/blocks/{id}/children` |
+| `append_block_children` | `append_block_children()` | `PATCH /v1/blocks/{id}/children` |
+| `update_block` | `update_block()` | `PATCH /v1/blocks/{id}` |
+| `delete_block` | `delete_block()` | `DELETE /v1/blocks/{id}` |
+
+### Users
+| Tool | SDK Method | Notion Endpoint |
+|---|---|---|
+| `get_users` | `get_users()` | `GET /v1/users` |
+| `get_self` | `get_self()` | `GET /v1/users/me` |
+
+### Comments
+| Tool | SDK Method | Notion Endpoint |
+|---|---|---|
+| `create_comment` | `create_comment()` | `POST /v1/comments` |
+| `get_comments` | `get_comments()` | `GET /v1/comments` |
+
+### Search
+| Tool | SDK Method | Notion Endpoint |
+|---|---|---|
+| `search` | `search()` | `POST /v1/search` |
+
+**24 tools total** covering the complete Notion API v2025-09-03 surface.
+
+## Architecture
+
+```
+notion-mcp/
+├── src/
+│   └── notion_mcp/
+│       ├── server.py          # MCP server entry point
+│       ├── tools/
+│       │   ├── pages.py       # Page tools
+│       │   ├── databases.py   # Database & data source tools
+│       │   ├── blocks.py      # Block tools
+│       │   ├── users.py       # User tools
+│       │   ├── comments.py    # Comment tools
+│       │   └── search.py      # Search tools
+│       └── ...
+├── tests/
+├── pyproject.toml
+└── README.md
+```
+
+Each tool module mirrors the SDK's mixin structure, keeping a clean 1:1 mapping.
+
+## Prerequisites
+
+- Python >= 3.10
+- A Notion integration API key (`NOTION_API_KEY`)
+- [`notion-sdk`](https://github.com/ldraney/notion-sdk) (installed as a dependency)
+
+## Setup
+
+```bash
+# Clone
+git clone https://github.com/ldraney/notion-mcp.git
+cd notion-mcp
+
+# Install
+pip install -e .
+
+# Configure
+export NOTION_API_KEY="ntn_..."
+```
+
+## Usage
+
+### With Claude Code
+
+Add to your Claude Code MCP config (`~/.claude/settings.json` or project settings):
+
+```json
+{
+  "mcpServers": {
+    "notion": {
+      "command": "python",
+      "args": ["-m", "notion_mcp"],
+      "env": {
+        "NOTION_API_KEY": "ntn_..."
+      }
+    }
+  }
+}
+```
+
+### Standalone
+
+```bash
+python -m notion_mcp
+```
+
+## Related
+
+- [`ldraney/notion-sdk`](https://github.com/ldraney/notion-sdk) — The underlying Python SDK this server wraps

ldraney_notion_mcp-0.1.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+notion_mcp/__init__.py,sha256=Wy2Os0Ww79mbGvySlmb9IVPW9t-oUPO246-8PppLqUI,105
+notion_mcp/__main__.py,sha256=8iuAFwnkWnvYNFN7qLyPeNa-qlKbzQMO6b7li5yrRFU,83
+notion_mcp/server.py,sha256=V_1bPrjEHh2LgmPR4lZQpUMEiVJiL2yGG1j8Lxkzwpc,2242
+notion_mcp/tools/__init__.py,sha256=Dak6lGr2H_aG5SYNAfi_1lACTqwAPDAAjIyVmGja8as,496
+notion_mcp/tools/blocks.py,sha256=9OTGJS6XhRzZe0sZk1ArgN-gyGmfcuTMek7HnhNk-ew,2674
+notion_mcp/tools/comments.py,sha256=eLPQZSIDd6wae9hVcnp5v_TpMu9a01k7wUJpjNBnq4E,1792
+notion_mcp/tools/databases.py,sha256=7L_M7Y-AX82S24TuZY88sJ6SoEECnZkq3muKYTExjqk,7360
+notion_mcp/tools/pages.py,sha256=8FuUCJwASwt17IfpqO3dJWoz-FwXarKJC8VlHz53oX4,3638
+notion_mcp/tools/search.py,sha256=FwaiR-4vQ7SwGcCNKvVeMBk9TLTWrtlAi_Baf9HYyw8,1188
+notion_mcp/tools/users.py,sha256=C0ytVNk7lDpQfcw4Wir39QII97LUtINf62j7fKpD-IQ,945
+ldraney_notion_mcp-0.1.1.dist-info/METADATA,sha256=vZtf860GXTOnmRFz7hQAAT2Cm-Z1hqQhpH9mX77QvsI,4542
+ldraney_notion_mcp-0.1.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ldraney_notion_mcp-0.1.1.dist-info/top_level.txt,sha256=lFXGlrgRGHEtgwNKPCohd0H0PxUReLzGdpd6YzborzM,11
+ldraney_notion_mcp-0.1.1.dist-info/RECORD,,

ldraney_notion_mcp-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ldraney_notion_mcp-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+notion_mcp

notion_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""notion-mcp: MCP server wrapping the Notion Python SDK."""
+
+from .server import mcp
+
+__all__ = ["mcp"]

notion_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m notion_mcp`."""
+
+from .server import mcp
+
+mcp.run()

notion_mcp/server.py

@@ -0,0 +1,74 @@
+"""MCP server entry point — FastMCP app and NotionClient lifecycle."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+from notion_sdk import NotionClient
+
+mcp = FastMCP("notion")
+
+# ---------------------------------------------------------------------------
+# Shared client instance
+# ---------------------------------------------------------------------------
+
+_client: NotionClient | None = None
+
+
+def get_client() -> NotionClient:
+    """Return the shared NotionClient, creating it on first call.
+
+    The client reads NOTION_API_KEY from the environment (via the SDK).
+    """
+    global _client
+    if _client is None:
+        _client = NotionClient()
+    return _client
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_json(value: str | dict | list | None, name: str) -> Any:
+    """Parse a JSON string into a Python object, or pass through if already parsed."""
+    if value is None:
+        return None
+    if isinstance(value, (dict, list)):
+        return value
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON for parameter '{name}': {exc}") from exc
+
+
+def _error_response(exc: Exception) -> str:
+    """Format an exception into a user-friendly error string."""
+    if isinstance(exc, httpx.HTTPStatusError):
+        try:
+            body = exc.response.json()
+        except Exception:
+            body = exc.response.text
+        return json.dumps(
+            {
+                "error": True,
+                "status_code": exc.response.status_code,
+                "message": str(exc),
+                "details": body,
+            },
+            indent=2,
+        )
+    return json.dumps({"error": True, "message": str(exc)}, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Register tool modules — each module calls @mcp.tool() at import time
+# ---------------------------------------------------------------------------
+
+from .tools import register_all_tools  # noqa: E402
+
+register_all_tools()

notion_mcp/tools/__init__.py

@@ -0,0 +1,13 @@
+"""Tool registration — imports every tool module so @mcp.tool() decorators fire."""
+
+from __future__ import annotations
+
+
+def register_all_tools() -> None:
+    """Import all tool modules, which register tools via the module-level @mcp.tool() decorators."""
+    from . import pages  # noqa: F401
+    from . import databases  # noqa: F401
+    from . import blocks  # noqa: F401
+    from . import users  # noqa: F401
+    from . import comments  # noqa: F401
+    from . import search  # noqa: F401

notion_mcp/tools/blocks.py

@@ -0,0 +1,100 @@
+"""Block tools — wraps BlocksMixin methods."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..server import mcp, get_client, _parse_json, _error_response
+
+
+@mcp.tool()
+def get_block(block_id: str) -> str:
+    """Retrieve a Notion block by its ID.
+
+    Args:
+        block_id: The UUID of the block to retrieve.
+    """
+    try:
+        result = get_client().get_block(block_id)
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def get_block_children(
+    block_id: str,
+    start_cursor: str | None = None,
+    page_size: int | None = None,
+) -> str:
+    """List child blocks of a Notion block.
+
+    Args:
+        block_id: The UUID of the parent block.
+        start_cursor: Optional cursor for pagination.
+        page_size: Optional number of results per page.
+    """
+    try:
+        result = get_client().get_block_children(
+            block_id,
+            start_cursor=start_cursor,
+            page_size=page_size,
+        )
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def append_block_children(block_id: str, children: str) -> str:
+    """Append child blocks to a Notion block.
+
+    Args:
+        block_id: The UUID of the parent block to append children to.
+        children: JSON string for a list of block objects to append.
+    """
+    try:
+        result = get_client().append_block_children(
+            block_id,
+            children=_parse_json(children, "children"),
+        )
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def update_block(
+    block_id: str,
+    content: str | None = None,
+) -> str:
+    """Update a Notion block.
+
+    Args:
+        block_id: The UUID of the block to update.
+        content: JSON string of block properties to update. The keys depend
+            on the block type (e.g. {"paragraph": {"rich_text": [...]}}).
+    """
+    try:
+        kwargs: dict[str, Any] = {}
+        if content is not None:
+            kwargs = _parse_json(content, "content")
+        result = get_client().update_block(block_id, **kwargs)
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def delete_block(block_id: str) -> str:
+    """Delete (archive) a Notion block.
+
+    Args:
+        block_id: The UUID of the block to delete.
+    """
+    try:
+        result = get_client().delete_block(block_id)
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)

notion_mcp/tools/comments.py

@@ -0,0 +1,61 @@
+"""Comment tools — wraps CommentsMixin methods."""
+
+from __future__ import annotations
+
+import json
+
+from ..server import mcp, get_client, _parse_json, _error_response
+
+
+@mcp.tool()
+def create_comment(
+    parent: str,
+    rich_text: str,
+    discussion_id: str | None = None,
+) -> str:
+    """Create a comment on a Notion page or block.
+
+    Args:
+        parent: JSON string for the parent object,
+            e.g. {"page_id": "..."}.
+        rich_text: JSON string for the rich-text content array,
+            e.g. [{"type": "text", "text": {"content": "Hello!"}}].
+        discussion_id: Optional UUID of an existing discussion thread
+            to reply to. Omit to start a new top-level comment.
+    """
+    try:
+        kwargs: dict[str, object] = {}
+        if discussion_id is not None:
+            kwargs["discussion_id"] = discussion_id
+        result = get_client().create_comment(
+            parent=_parse_json(parent, "parent"),
+            rich_text=_parse_json(rich_text, "rich_text"),
+            **kwargs,
+        )
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def get_comments(
+    block_id: str,
+    start_cursor: str | None = None,
+    page_size: int | None = None,
+) -> str:
+    """List comments on a Notion block or page.
+
+    Args:
+        block_id: The UUID of the block or page to list comments for.
+        start_cursor: Optional cursor for pagination.
+        page_size: Optional number of results per page.
+    """
+    try:
+        result = get_client().get_comments(
+            block_id,
+            start_cursor=start_cursor,
+            page_size=page_size,
+        )
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)

notion_mcp/tools/databases.py

@@ -0,0 +1,236 @@
+"""Database and data source tools — wraps DatabasesMixin methods."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..server import mcp, get_client, _parse_json, _error_response
+
+
+# ---------------------------------------------------------------------------
+# Database tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def create_database(
+    parent: str,
+    title: str,
+    initial_data_source: str | None = None,
+) -> str:
+    """Create a new Notion database.
+
+    In Notion API v2025-09-03, database properties live on data sources.
+    Pass properties inside initial_data_source.properties.
+
+    Args:
+        parent: JSON string for the parent object, e.g. {"type": "page_id", "page_id": "..."}.
+        title: JSON string for the title rich-text array,
+            e.g. [{"type": "text", "text": {"content": "My DB"}}].
+        initial_data_source: Optional JSON string for the initial data source
+            configuration including properties.
+    """
+    try:
+        result = get_client().create_database(
+            parent=_parse_json(parent, "parent"),
+            title=_parse_json(title, "title"),
+            initial_data_source=_parse_json(initial_data_source, "initial_data_source"),
+        )
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def get_database(database_id: str) -> str:
+    """Retrieve a Notion database by its ID.
+
+    Note: In v2025-09-03 the response contains data_sources but NOT
+    properties. Use get_data_source to inspect properties.
+
+    Args:
+        database_id: The UUID of the database to retrieve.
+    """
+    try:
+        result = get_client().get_database(database_id)
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def update_database(
+    database_id: str,
+    title: str | None = None,
+    description: str | None = None,
+    icon: str | None = None,
+    cover: str | None = None,
+) -> str:
+    """Update a Notion database.
+
+    Args:
+        database_id: The UUID of the database to update.
+        title: Optional JSON string for the new title rich-text array.
+        description: Optional JSON string for the description rich-text array.
+        icon: Optional JSON string for the database icon.
+        cover: Optional JSON string for the database cover.
+    """
+    try:
+        kwargs: dict[str, Any] = {}
+        if title is not None:
+            kwargs["title"] = _parse_json(title, "title")
+        if description is not None:
+            kwargs["description"] = _parse_json(description, "description")
+        if icon is not None:
+            kwargs["icon"] = _parse_json(icon, "icon")
+        if cover is not None:
+            kwargs["cover"] = _parse_json(cover, "cover")
+        result = get_client().update_database(database_id, **kwargs)
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def archive_database(database_id: str) -> str:
+    """Archive a Notion database.
+
+    Args:
+        database_id: The UUID of the database to archive.
+    """
+    try:
+        result = get_client().archive_database(database_id)
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def query_database(
+    database_id: str,
+    filter: str | None = None,
+    sorts: str | None = None,
+    start_cursor: str | None = None,
+    page_size: int | None = None,
+) -> str:
+    """Query a Notion database for pages/rows.
+
+    Automatically resolves the first data source and queries it.
+    If you already know the data source ID, use query_data_source instead.
+
+    Args:
+        database_id: The UUID of the database to query.
+        filter: Optional JSON string for a filter object.
+        sorts: Optional JSON string for a list of sort objects.
+        start_cursor: Optional cursor for pagination.
+        page_size: Optional number of results per page.
+    """
+    try:
+        result = get_client().query_database(
+            database_id,
+            filter=_parse_json(filter, "filter"),
+            sorts=_parse_json(sorts, "sorts"),
+            start_cursor=start_cursor,
+            page_size=page_size,
+        )
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+# ---------------------------------------------------------------------------
+# Data source tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def get_data_source(data_source_id: str) -> str:
+    """Retrieve a Notion data source (includes properties).
+
+    Args:
+        data_source_id: The UUID of the data source to retrieve.
+    """
+    try:
+        result = get_client().get_data_source(data_source_id)
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def update_data_source(
+    data_source_id: str,
+    properties: str | None = None,
+) -> str:
+    """Update a Notion data source.
+
+    Args:
+        data_source_id: The UUID of the data source to update.
+        properties: Optional JSON string for properties to update.
+    """
+    try:
+        kwargs: dict[str, Any] = {}
+        if properties is not None:
+            kwargs["properties"] = _parse_json(properties, "properties")
+        result = get_client().update_data_source(data_source_id, **kwargs)
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def query_data_source(
+    data_source_id: str,
+    filter: str | None = None,
+    sorts: str | None = None,
+    start_cursor: str | None = None,
+    page_size: int | None = None,
+) -> str:
+    """Query rows in a Notion data source.
+
+    Args:
+        data_source_id: The UUID of the data source to query.
+        filter: Optional JSON string for a filter object.
+        sorts: Optional JSON string for a list of sort objects.
+        start_cursor: Optional cursor for pagination.
+        page_size: Optional number of results per page.
+    """
+    try:
+        result = get_client().query_data_source(
+            data_source_id,
+            filter=_parse_json(filter, "filter"),
+            sorts=_parse_json(sorts, "sorts"),
+            start_cursor=start_cursor,
+            page_size=page_size,
+        )
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def list_data_source_templates(
+    data_source_id: str,
+    name: str | None = None,
+    start_cursor: str | None = None,
+    page_size: int | None = None,
+) -> str:
+    """List templates for a Notion data source.
+
+    Args:
+        data_source_id: The UUID of the data source.
+        name: Optional name filter for templates.
+        start_cursor: Optional cursor for pagination.
+        page_size: Optional number of results per page.
+    """
+    try:
+        result = get_client().list_data_source_templates(
+            data_source_id,
+            name=name,
+            start_cursor=start_cursor,
+            page_size=page_size,
+        )
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)

notion_mcp/tools/pages.py

@@ -0,0 +1,121 @@
+"""Page tools — wraps PagesMixin methods."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..server import mcp, get_client, _parse_json, _error_response
+
+
+@mcp.tool()
+def create_page(
+    parent: str,
+    properties: str,
+    children: str | None = None,
+    template: str | None = None,
+) -> str:
+    """Create a new Notion page.
+
+    Args:
+        parent: JSON string for the parent object, e.g. {"type": "page_id", "page_id": "..."}.
+        properties: JSON string for the page properties mapping.
+        children: Optional JSON string for a list of block children to append.
+            Cannot be used together with template.
+        template: Optional JSON string for a data-source template, e.g.
+            {"type": "none"}, {"type": "default"}, or
+            {"type": "template_id", "template_id": "<uuid>"}.
+    """
+    try:
+        result = get_client().create_page(
+            parent=_parse_json(parent, "parent"),
+            properties=_parse_json(properties, "properties"),
+            children=_parse_json(children, "children"),
+            template=_parse_json(template, "template"),
+        )
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def get_page(page_id: str) -> str:
+    """Retrieve a Notion page by its ID.
+
+    Args:
+        page_id: The UUID of the page to retrieve.
+    """
+    try:
+        result = get_client().get_page(page_id)
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def update_page(
+    page_id: str,
+    properties: str | None = None,
+    erase_content: bool | None = None,
+    icon: str | None = None,
+    cover: str | None = None,
+) -> str:
+    """Update a Notion page's properties, icon, or cover.
+
+    Args:
+        page_id: The UUID of the page to update.
+        properties: Optional JSON string of properties to update.
+        erase_content: If true, clears ALL block content from the page.
+            WARNING: This is destructive and irreversible.
+        icon: Optional JSON string for the page icon.
+        cover: Optional JSON string for the page cover.
+    """
+    try:
+        kwargs: dict[str, Any] = {}
+        if properties is not None:
+            kwargs["properties"] = _parse_json(properties, "properties")
+        if icon is not None:
+            kwargs["icon"] = _parse_json(icon, "icon")
+        if cover is not None:
+            kwargs["cover"] = _parse_json(cover, "cover")
+        result = get_client().update_page(
+            page_id,
+            erase_content=erase_content,
+            **kwargs,
+        )
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def archive_page(page_id: str) -> str:
+    """Archive (soft-delete) a Notion page.
+
+    Args:
+        page_id: The UUID of the page to archive.
+    """
+    try:
+        result = get_client().archive_page(page_id)
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def move_page(page_id: str, parent: str) -> str:
+    """Move a Notion page to a new parent.
+
+    Args:
+        page_id: The UUID of the page to move.
+        parent: JSON string for the new parent object,
+            e.g. {"type": "page_id", "page_id": "..."}.
+    """
+    try:
+        result = get_client().move_page(
+            page_id,
+            parent=_parse_json(parent, "parent"),
+        )
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)

notion_mcp/tools/search.py

@@ -0,0 +1,39 @@
+"""Search tool — wraps SearchMixin method."""
+
+from __future__ import annotations
+
+import json
+
+from ..server import mcp, get_client, _parse_json, _error_response
+
+
+@mcp.tool()
+def search(
+    query: str | None = None,
+    filter: str | None = None,
+    sort: str | None = None,
+    start_cursor: str | None = None,
+    page_size: int | None = None,
+) -> str:
+    """Search Notion pages and databases.
+
+    Args:
+        query: Optional text query to search for.
+        filter: Optional JSON string for a filter object,
+            e.g. {"value": "page", "property": "object"}.
+        sort: Optional JSON string for a sort object,
+            e.g. {"direction": "ascending", "timestamp": "last_edited_time"}.
+        start_cursor: Optional cursor for pagination.
+        page_size: Optional number of results per page.
+    """
+    try:
+        result = get_client().search(
+            query=query,
+            filter=_parse_json(filter, "filter"),
+            sort=_parse_json(sort, "sort"),
+            start_cursor=start_cursor,
+            page_size=page_size,
+        )
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)

notion_mcp/tools/users.py

@@ -0,0 +1,38 @@
+"""User tools — wraps UsersMixin methods."""
+
+from __future__ import annotations
+
+import json
+
+from ..server import mcp, get_client, _error_response
+
+
+@mcp.tool()
+def get_users(
+    start_cursor: str | None = None,
+    page_size: int | None = None,
+) -> str:
+    """List all users in the Notion workspace.
+
+    Args:
+        start_cursor: Optional cursor for pagination.
+        page_size: Optional number of results per page.
+    """
+    try:
+        result = get_client().get_users(
+            start_cursor=start_cursor,
+            page_size=page_size,
+        )
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)
+
+
+@mcp.tool()
+def get_self() -> str:
+    """Retrieve the bot user associated with the current API token."""
+    try:
+        result = get_client().get_self()
+        return json.dumps(result, indent=2)
+    except Exception as exc:
+        return _error_response(exc)