mcp-notion-patterns
Patterns for using the Notion MCP server with mcp-cli.
- License 许可
- MIT
- 最近更新
- 2026-10-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- mcp-notion-patterns
- author
- community
- license
- MIT
- version
- 0.2.0
- metadata
- { "hermes": { "tags": [ "MCP", "Notion", "Productivity", "Database", "API", "CLI" ], "homepage": "https://developers.notion.com" } }
- platforms
- [ "linux", "macos", "windows" ]
- description
- Patterns for using the Notion MCP server with mcp-cli.
- prerequisites
- { "env_vars": [ "NOTION_TOKEN" ], "alt_config_path": "~/.mcp_servers.json" }
02 资源文件 2
03 SKILL.md 正文
MCP Notion Patterns
This skill provides patterns for working with the Notion MCP server (@notionhq/notion-mcp-server) via mcp-cli.
WORKFLOW RULE (user preference — non-negotiable on this project)
When a Notion MCP is configured and reachable, drive page create/import/read through mcp-cli call notion ... — do NOT hand-roll raw curl/urllib blocks against the Notion REST API. The user explicitly pushed back when an export was done via raw HTTP instead of the MCP ("why are you not using the mcp that talks directly to notion api using mcp-cli that can direct it accurately"). The MCP path is:
- less error-prone (no manual auth header juggling),
- the path the user expects by default,
- fully capable of full-fidelity page import via the
markdownbody (see references/mcp-cli-notion-bulk-import.md).
Use raw HTTP only as a fallback when the MCP tool genuinely lacks the needed capability (e.g. archiving many pages in bulk, or paginating >100 children).
Why this rule exists (user signal)
During a 4-vault Obsidian→Notion export the agent first used hand-rolled curl/urllib against the REST API. The user stopped it with: "why are you not using the mcp that talks directly to notion api using mcp-cli that can direct it accurately". Lesson: when a Notion MCP is configured, default to mcp-cli call notion ... without being asked. Reaching for curl first reads as the wrong path to this user even when curl would work.
Dispatch gotchas (learned hands-on)
- Pass args via
subprocess input=, never as an argv string. Large markdown bodies hit OSARG_MAX("Argument list too long") for notes >~150 KB. In Python:subprocess.run(["mcp-cli","call","notion",tool], input=json.dumps(args).encode(), capture_output=True, text=False). - Empty search:
API-post-searchwith no args or{}returns 0 results. To enumerate everything, pass{"query":""}(empty string, not omitted). Broadquery:"a"also returns 0 — search matches titles/text, not wildcards. - Response envelope: unwrap
content[0].textbeforejson.loads. Seereferences/mcp-cli-notion-bulk-import.md. - Run bulk jobs in background (
background=true,notify_on_complete=true) — each call cold-spawnsnpx(~5–7 s); 400+ calls block a foreground loop.
Setup
Ensure you have the Notion MCP server configured in ~/.mcp_servers.json:
{
"mcpServers": {
"notion": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server@latest"],
"env": {
"NOTION_TOKEN": "ntn_your_token_here"
}
}
}
}
The server reads NOTION_TOKEN from the environment.
Pattern: Enumerating Accessible Databases
To find which databases (data sources) the integration can access, use API-post-search with an empty query. The results may include pages inside databases and the data sources themselves.
mcp-cli call notion API-post-search '{}' 2>/dev/null > /tmp/notion_search.json
Extracting Data Source IDs
Filter the results for objects with "object": "data_source" to get the database IDs needed for API-query-data-source.
Using jq:
jq '.results[] | select(.object == "data_source") | .id' /tmp/notion_search.json
Using python3:
python3 -c "import json; data=json.load(open('/tmp/notion_search.json')); [print(r['id']) for r in data['results'] if r.get('object') == 'data_source']"
If No Data Sources Appear
If the filtering returns no results, the integration likely has not been granted access to any databases. In Notion, share the desired database with the integration:
- Open the database in Notion.
- Click "Share" → "Connect" → select your integration.
Pattern: Querying a Database
Once you have a data_source_id, use API-query-data-source to retrieve rows. The tool expects JSON input via stdin.
Example: Get all rows from a database:
echo '{"data_source_id": "your-data-source-id-here"}' | mcp-cli call notion API-query-data-source
Example: Filter by a select property:
echo '{"data_source_id": "your-data-source-id-here", "filter": {"property": "Status", "select": {"equals": "Done"}}}' | mcp-cli call notion API-query-data-source
Pattern: Creating a Page in a Database
To create a new page in a database, use API-post-page. You need the database_id (not the data_source_id). The database_id can be found in the parent of a page inside the database, or by retrieving the data source and looking for database_id in its properties (though the MCP server may not expose it directly).
Alternatively, you can use the ntn CLI or HTTP API to create a page if you have the database_id.
Bulk import / Obsidian export (deep dive)
The reference references/mcp-cli-notion-bulk-import.md covers the non-obvious, hard-won behaviors for bulk page creation:
- the
mcp-cliresponse envelope (unwrapcontent[0].text), API-post-pageaccepting amarkdownbody for full-fidelity import,API-update-page-markdownis diff-based (NOT a body setter),- the ~50 KB markdown body cap and how to split large notes,
child_page.titlelocation for fast child enumeration,- idempotency / duplicate-page avoidance,
- wikilink and embed limitations.
A ready-to-run bulk exporter lives at scripts/mcp_notion_markdown_exporter.py (TSV of title+markdown-file → Notion pages, with auto-chunking and envelope unwrap). Read the reference before any multi-page export.
Troubleshooting
- 401 Unauthorized: Verify
NOTION_TOKENis set correctly (notNOTION_API_KEY). - Empty results from API-post-search: Check that the integration is shared with the desired pages/databases.
- Tool call timeouts: Use
MCP_NO_DAEMON=1prefix to force fresh connections. - mcp-cli returns zero bytes: The MCP server may be failing silently. Fall back to direct HTTP calls using the token from
~/.mcp_servers.json.
Notes
- The Notion MCP server uses the API version specified by the server; ensure it matches your integration's expectations.
- Rate limits apply (~3 requests/second average).
- For rich page creation with blocks, prefer the MCP server over raw API calls.
04 同仓库更多 Skills
blocked-page-recovery
Use when a fetch fails: 403/429, paywall, WAF, bot wall.
gemini-vision-fallback
Vision fallback: Gemini REST API if vision_analyze blocked.
twitter-cli
Use twitter-cli for ALL Twitter/X operations — reading tweets, posting, replying, quoting, liking, retweeting, following, searching, user lookups. Invoke whenever user requests any Twitter interaction.
prism-scan
Structural analysis through dynamically generated cognitive lenses. Generates the optimal analytical lens for the specific code/artifact, then executes it. Finds conservation laws, structural invariants, and concrete bugs that vanilla analysis misses. Use on any code file, system design, or text artifact.
prism-reflect
Constraint transparency: analyzes an artifact structurally, then analyzes what its own analysis concealed. Produces a conservation law AND a constraint report showing what was maximized, what was sacrificed, and what to investigate next. The only AI skill that knows what it can't see.
prism-full
Full Prism: multi-pass structural analysis with mandatory adversarial self-correction. Designs custom analytical passes, executes them with chaining, then attacks its own findings before synthesizing. Use for maximum depth on important code or artifacts.