drn/notion

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)