aufrank/querying-notion-programmatically
skills/querying-notion-programmatically/SKILL.md
Run Notion MCP searches for pages/blocks and fetch page comments via mcpc-backed Python wrappers. Use when Codex needs deterministic, file-backed Notion queries (filters come later).
tools
Updated Apr 3, 2026
$ install --global
skillsauthnpx skillsauth add aufrank/agent-skills querying-notion-programmaticallyInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 3, 2026, 11:54 AM4.2s7 files scanned
SKILL.md
- name:
- querying-notion-programmatically
- description:
- >
- version:
- 0.1.0
Querying Notion Programmatically
Overview
- Code Mode skill for issuing Notion searches (pages/blocks/users) and fetching page comments through mcpc helper scripts.
- Favors deterministic loops: auth preflight, plan file, execute wrapper scripts, read results from disk (never paste big payloads in chat).
- Scope now: queries only; add filters/date/creator later.
Quick Start (examples)
- Search workspace:
python <CODEX_HOME>/skills/querying-notion-programmatically/scripts/notion_query.py --query "AI ML" --pretty - Fetch comments:
python <CODEX_HOME>/skills/querying-notion-programmatically/scripts/notion_comments.py --page-id <page-id-or-url> - Any tool (cached schemas):
python <CODEX_HOME>/skills/querying-notion-programmatically/scripts/notion_call_tool.py --tool notion-search --arg query:="AI" --refresh-cache - WSL bridge: prefix with
MCPC_BIN="<TOOL_HOME>"(optionalPOWERSHELL_EXE).
Prereqs & Auth
- Tools:
mcpcon PATH; Python 3.11+. - Manual login only (agent never opens browser):
mcpc https://mcp.notion.com/mcp login --profile <name>(defaultdefault). - Session defaults:
@notionsession, serverhttps://mcp.notion.com/mcp, profile fromMCP_PROFILEordefault. - WSL tip: reuse Windows keyring by setting
MCPC_BIN="<TOOL_HOME>"(PowerShell bridge). OptionalPOWERSHELL_EXEto point at a specific PowerShell.
Trust / Permissions
- Always: Read local files, inspect references/templates, view cached tool schemas on disk.
- Ask: Any mcpc call (network); packaging; writing results.
- Never: Destructive Notion actions (deletes/moves), credential exfil, auto-login/browser opening.
Canonical Loop
- Clarify query goal; if helpful, fill
templates/plan.query.json. - Ensure auth (scripts run preflight; if missing, user must login manually).
- Run
scripts/notion_query.pyfor search orscripts/notion_comments.pyfor comments. - Inspect outputs under
results/(JSON + optional pretty stdout). Reuse files instead of re-running. - Append notes to
progress.logif maintaining a trail; keep payloads out of chat.
Scripts (execute, don't call tools directly)
- scripts/notion_query.py: Run
notion-search(pages/blocks/users).
Flags:--query(required),--query-type internal|user(default internal),--ids-only,--pretty,--output(defaultresults/query.search.json),--session(default@notion),--profile,--server. Writes parsed payload; prints summary or IDs. - scripts/notion_comments.py: Fetch comments for a page ID/URL.
Flags:--page-id(required),--output(defaultresults/comments.json),--session,--profile,--server. Writes comments payload and pretty-prints concise lines. - scripts/notion_call_tool.py: Generic mcpc caller with cached
mcp_tools/tools-list.jsonandmcp_tools/<tool>.json.
Flags:--tool <name>(required), repeatable--arg key:=value,--output(defaultresults/<tool>.json),--refresh-cache,--session/@notion,--profile,--server. Warns if tool missing from cached list; always writes output JSON. - scripts/notion_common.py: Shared auth preflight (
tools-list), mcpc path resolution, file writers. Auto-creates output parent dirs.
Templates
templates/plan.query.json: Lightweight plan scaffold (query text, query_type, intended outputs). Duplicate/edit per run; keep alongsideresults/.
References
references/usage.md: Quick reminders on commands, outputs, and resuming.mcp_tools/(optional, create when needed): Cache tool schemas viamcpc --json @notion tools-get notion-search > mcp_tools/notion-search.jsonto avoid large payloads in context.
Outputs & Restart
- Scripts write to
results/(JSON, optional ID text). Keep payloads on disk; cite file paths in chat. - To resume: read
results/query.search.jsonorresults/comments.json; re-run scripts only if inputs change.
Packaging
- Validate + package when done:
python <REPO_ROOT>/skills/creating-mcp-code-mode-skills/scripts/package_skill.py <REPO_ROOT>/skills/querying-notion-programmatically dist
Related Skills
aufrank/running-dag-pipelines
tools
VerifiedTrustedCommunity
Build and execute modular DAG workflows for long-context processing using slice/map/reduce/recurse/compact/filter operators. Use for one-shot batch jobs, standalone map-reduce pipelines, or when the context-dag plugin is not installed. Trigger when input exceeds the model's context window, when reproducible logged pipelines are needed, or when multi-level recursive processing is required. If context-dag is installed, the plugin's bundled dag_runner.py provides the same capability with persistent artifact storage.
SKILL.mdUpdated May 7, 2026
aufrank/austin-frank-voice
documentation
VerifiedTrustedCommunity
Write in Austin Frank's voice and style. Use this skill whenever generating text that should sound like Austin — strategy docs, charters, proposals, business cases, vision documents, staffing requests, stakeholder updates, cover letters, mission statements, org design documents, or any professional prose where the user wants Austin's distinctive voice. Also use when the user asks to review, edit, or improve a draft for voice consistency, or when they reference "my style", "my voice", "write like me", or "Austin's style".
SKILL.mdUpdated May 7, 2026
aufrank/working-with-notion-programmatically
tools
VerifiedTrustedCommunity
Use mcpc to interact with the Notion MCP server: connect sessions, search workspace content, fetch pages/databases, and run helper scripts for common Notion actions.
SKILL.mdUpdated Apr 3, 2026
aufrank/workflow-or-agent-decider
tools
VerifiedTrustedCommunity
Decide between a scripted workflow and an autonomous agent harness, then scaffold the chosen path. Use when scoping new agentic systems or tool integrations.
SKILL.mdUpdated Apr 3, 2026