tiny-notion-mcp

Why?

The official Notion MCP server returns raw Notion API JSON — deeply nested, metadata-heavy payloads that consume thousands of tokens per response. In LLM-powered workflows, token usage directly translates to latency, cost, and context pressure.

tiny-notion-mcp takes a different approach: every tool returns the smallest useful representation.

In practice this cuts token consumption by ~60-90% on read-heavy workflows, while remaining fully compatible with the MCP protocol.

Architecture

flowchart LR
    subgraph Client["MCP Client (Claude, Cursor, etc.)"]
        direction TB
        C1["notion_search(query)"]
        C2["notion_read(page_id)"]
        C3["notion_write(markdown)"]
        C4["notion_query_database(db_id)"]
        C5["notion_create_page(...)"]
        C6["notion_update_page(...)"]
        C7["notion_get_blocks(...)"]
        C8["notion_delete_block/delete_page(...)"]
    end

    subgraph Server["tiny-notion-mcp (stdio)"]
        SERVER["MCP Server"]
        CORE["Core Logic\n• Markdown ↔ Notion blocks\n• Inline formatting\n• Table handling\n• Pagination"]
    end

    subgraph Notion["Notion API"]
        API["notion-client SDK"]
    end

    C1 & C2 & C3 & C4 & C5 & C6 & C7 & C8 -->|"JSON-RPC"| SERVER
    SERVER --> CORE
    CORE --> API
    API --> NotionAPI["api.notion.com"]

The server uses an abstract NotionClient interface, making the core logic fully testable without a Notion account. A production implementation wraps the notion-client SDK; tests use a lightweight mock.

Tools

TOON format

Search results and page creation responses use the compact TOON format:

Page title | page-id | https://notion.so/... | parent:<parent-id>

One line per result. No nested JSON. No metadata noise.

Installation

Prerequisites: uv and a Notion integration token.

git clone https://github.com/AyanoT1/tiny-notion-mcp
cd tiny-notion-mcp
uv tool install .

Connect to your MCP client

Claude Desktop (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "tiny-notion-mcp": {
      "command": "uvx",
      "args": ["tiny-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

Cursor / VS Code with an MCP client:

{
  "mcpServers": {
    "tiny-notion-mcp": {
      "command": "uvx",
      "args": ["tiny-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

Note: Before using the tools, connect the integration to any Notion pages or databases you want it to access via the Notion UI (⋮ → Connections → Add integration).

Supported block types

Read (Notion → Markdown)

All inline formatting (bold, italic, bold-italic, strikethrough, underline, inline code, links) is preserved in Markdown.

Write (Markdown → Notion)

Markdown is parsed and appended to the target page as native Notion blocks. Large content is automatically split into batches of 50 to respect the Notion API limit. Tables are sent with embedded child rows in a single API call.

Tip: Use notion_get_blocks to find a block ID, then pass it as after_block_id to notion_write to insert content at a specific position rather than the page end.

Known limitations

• Toggle blocks, table of contents, files, images, and videos are silently skipped on read and cannot be written.

• Empty paragraph blocks are not round-tripped. Spacer paragraphs in Notion are lost on a read → write cycle. This is inherent to a flat Markdown representation.

• Table header flag is not round-tripped. The writer always sets has_column_header: true because standard Markdown tables imply a header.

Design principles

1. Token efficiency first. Every response is minimal while remaining actionable.

2. No intermediate files. All content is returned inline as strings — no temp files, no file paths.

3. Testable without a Notion account. The NotionClient interface is injected; core logic is fully isolated.

4. Native Notion types. Markdown is converted to real Notion blocks (headings, lists, tables, code blocks, callouts, quotes, to-dos) — not flat text dumps.

Development

git clone https://github.com/AyanoT1/tiny-notion-mcp
cd tiny-notion-mcp
uv sync --dev
uv run pytest

Tests use a stub NotionClient and make no real API calls — no Notion account or token required.

To update a local Claude Code installation after making changes:

uv tool install . --force --no-cache

Then reconnect the MCP server from Settings → MCP → ⤓ Reconnect.

Roadmap

• Toggle block read/write support

• Image and file block support

• Table of contents block support

• Batch write operations

• .env file support for token configuration

• PyPI distribution

License

MIT © AyanoT1