---
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)