integration · notion

Claude + Notion — read, write, query.

Q: Internal integration vs public OAuth?

wmcp.sh's Notion provider is registered as a Public integration with OAuth — any wmcp user can connect their own Notion workspace. Internal integrations (single-workspace, no OAuth) work via the _auth arg if you'd rather pass the token directly.

Q: Can it read content from an existing page?

Yes. blocks.children.list returns the block tree for a page. For nested content, recursively call on child blocks. The agent can also pages.retrieve for property values.

Q: Database queries — how does filtering work?

databases.query accepts Notion's full filter/sort JSON. Tell the agent the database schema (or have it call databases.retrieve first), then have it build the filter. Compound filters with and/or nest as deep as Notion supports.

Notion's API is REST-shaped but its data model is unusual — pages, blocks, databases, properties, all schema-flexible. wmcp.sh wraps it as clean MCP tools your agent can call without learning Notion's quirks. Connect once, the worker handles OAuth.

Last updated 2026-05-28 · works with Claude, OpenAI, LangChain, and any MCP client

Positioning

vs. the alternatives

Capability	@notionhq/client SDK	Composio Notion	wmcp.sh
Setup time	Install SDK + integration token	Composio platform + OAuth flow	Connect Notion once in dashboard
Workspace OAuth	Internal-only by default	Composio manages	Public OAuth + token vault
MCP shape	Wrap each call yourself	Auto-mapped	Native MCP tools
Database queries	Raw filter/sort JSON	Curated query helpers	Tool args mirror Notion's filter shape
Pagination	You handle cursors	Composio handles	Cursor surfaced to agent
Cost	Free SDK	Platform tier	Free 100/day + $29/mo Pro

What you get

Tools your agent calls

All MCP-shaped — consumed directly by Claude tool_use, OpenAI function-calling, or LangChain.

Tool	Type	Returns
`search`	Live action	Pages + databases matching a query
`pages.retrieve`	Live action	Page properties
`pages.create`	Live action	New page ID + URL
`blocks.children.append`	Live action	Appended blocks
`blocks.children.list`	Live action	Page content (blocks)
`databases.query`	Live action	Filtered + sorted rows
`databases.retrieve`	Live action	Database schema
`users.me`	Live action	Current OAuth user

Integrate

Python — agent files a note into a Notion database

from wmcp import WmcpClient
from wmcp.anthropic import to_anthropic_tools, execute_tool_use
from anthropic import Anthropic

client = WmcpClient(api_key="webmcp_live_…")
spec   = "https://api.notion.com/openapi"
tools  = [t for t in client.tools(spec)
          if t.name in {"pages_create", "databases_query", "search"}]

anthropic = Anthropic()
msg = anthropic.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=to_anthropic_tools(tools),
    messages=[{"role": "user",
               "content": "Add a note to my Inbox database: 'follow up with stripe re: Connect verification'."}],
)

for block in msg.content:
    if block.type == "tool_use":
        # Worker auto-injects your connected Notion OAuth token
        result = execute_tool_use(client, spec, block.model_dump())
        print(result)

FAQ

Frequently asked

Internal integration vs public OAuth?

wmcp.sh's Notion provider is registered as a Public integration with OAuth — any wmcp user can connect their own Notion workspace. Internal integrations (single-workspace, no OAuth) work via the _auth arg if you'd rather pass the token directly.

How does Notion's odd data model affect tool shape?

Notion's pages-have-blocks-have-children model is preserved. Each tool's input schema mirrors Notion's REST request body shape. Your agent passes the same JSON Notion's SDK would — wmcp doesn't try to flatten or simplify the model.

Can it read content from an existing page?

Yes. blocks.children.list returns the block tree for a page. For nested content, recursively call on child blocks. The agent can also pages.retrieve for property values.

Database queries — how does filtering work?

databases.query accepts Notion's full filter/sort JSON. Tell the agent the database schema (or have it call databases.retrieve first), then have it build the filter. Compound filters with and/or nest as deep as Notion supports.

Rate limits?

Notion's API: 3 requests/second average per integration. wmcp.sh doesn't add its own throttle — your agent's bursting hits Notion directly. For high-throughput use, batch operations where Notion supports it (e.g. append multiple blocks in one children.append call).

Docs agent-readiness

Notion overlaps with docs sites — same agent-discovery dynamics. See the docs-site guide for llms.txt + structured search.

→ /agent-ready/docs · cornerstone · done-for-you ($499+)

Need this done for you?

Skip the wiring — we build, deploy, and monitor.

Custom adapter + hosted MCP at mcp.yourbrand.com + verified badge. From $499 one-time setup.

See /managed → Submit (free)