notion

name	notion
description	Read Notion pages and databases using MCP tools. Use when looking up Notion content, reading pages, or querying databases.

Notion (Read-Only)

Read Notion pages and databases via MCP tools. This skill covers reading operations only.

Quick Reference: MCP Tools

Tool	Use For
mcp__notion__notion-fetch	Read page content as Notion-flavored markdown
ReadMcpResourceTool with notion://docs/enhanced-markdown-spec	Get the full markdown spec (useful for understanding page structure)

Fallback: Keystone MCP Tools

If mcp__notion__notion-fetch is not available (e.g., in environments using Keystone), use these tools instead:

Tool	Use For
mcp__plugin_thanx_keystone__notion_get_page	Read page metadata (title, properties, dates)
mcp__plugin_thanx_keystone__notion_get_page_content	Read page blocks (raw Notion API JSON)
mcp__plugin_thanx_keystone__notion_search	Search for pages by title
mcp__plugin_thanx_keystone__notion_query_database	Query a database with filters
mcp__plugin_thanx_keystone__notion_get_database	Get database schema and metadata

The blocks API returns raw JSON. To extract readable text, parse each block's rich_text[].plain_text fields. Use ToolSearch to discover and load these tools before calling them.

Instructions

You are helping read Notion data. Use the MCP tools above for all operations.

Reading a Page

mcp__notion__notion-fetch with the page URL or ID

The tool returns Notion-flavored markdown. Key things to know about the format:

• Code blocks have language tags (e.g., ```ruby)
• Toggle headings use {toggle="true"} attribute
• Toggle children are tab-indented
• Tables use HTML <table> syntax
• Dot-notation in text may appear auto-linked (e.g., [d.date](http://d.date))

Common Tasks

Read a specific page

Use mcp__notion__notion-fetch with the page URL.

Browse database contents

Use mcp__notion__notion-fetch on the database URL to see its schema and entries.

Diagnosing Page Issues

If a page has mangled content in the markdown output:

• Code blocks whose content starts with heading markers (#, ##)
• Code blocks containing <table or --- dividers
• Wrong language tags on code blocks

These indicate sections that were absorbed into code blocks during a bad edit.

Capabilities

• Page reading: Full page content as structured markdown
• Database browsing: View database schemas and entries

Large Page Handling

Notion pages can return very large responses (100K+ characters) that exceed token limits. When this happens:

• The content may be saved to a temp file automatically
• Use python3 -c or jq to extract block text rather than reading raw JSON directly
• For Keystone blocks JSON, extract text with: jq -r '.. | .rich_text? // empty | .[].plain_text' < temp_file.json
• Consider requesting specific sections rather than the full page when possible

Limitations

• Read-only — Cannot create, update, or delete pages
• Page content is returned as Notion-flavored markdown, not raw JSON (except Keystone fallback which returns raw blocks)