Which integrations are available for this server?

Allows interaction with Notion's API to search for pages and databases, retrieve page details, query database rows, create and update pages, and append content blocks.

How do I use Notion Remote MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Notion Remote MCP Server search for '2024 Project Roadmap' and summarize the content" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Notion Remote MCP Server (OAuth + PKCE)

Remote MCP server that connects to Notion via OAuth and exposes a practical, enterprise-friendly tool surface. It implements Streamable HTTP transport over POST /mcp, MCP-compatible OAuth endpoints, PKCE, token refresh, and encrypted token storage.

Quick Start (5 minutes)

Create a Notion integration

Create a public integration in Notion.
Add the OAuth redirect URL: http://localhost:8787/oauth/callback
Enable capabilities (least-privilege):
- Read content
- Update content
- Insert content
- Read user info

Configure env

cp .env.example .env

Generate an encryption key and HMAC secret:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Set:

TOKEN_ENC_KEY to the generated base64 key
STATE_SIGNING_KEY to another random secret
(Optional) TOKEN_ENC_KEY_FILE / STATE_SIGNING_KEY_FILE for file-based secrets (defaults under ./data/)
NOTION_CLIENT_ID / NOTION_CLIENT_SECRET
BASE_URL (if not localhost)
ALLOWED_REDIRECT_URIS for your MCP client
NOTION_VERSION (default: 2025-09-03)

npm install && npm run start

Server: http://localhost:8787

OAuth for MCP Clients

This server is an OAuth 2.1 Authorization Server for MCP clients and uses Notion OAuth behind the scenes.

Authorization URL:

GET /authorize?response_type=code&client_id=mcp-cli&redirect_uri=http://localhost:3000/callback&scope=notion.read%20notion.write&state=xyz&code_challenge=...&code_challenge_method=S256

Token endpoint:

POST /token (application/x-www-form-urlencoded)

Supported scopes:

notion.read
notion.write
notion.admin

Token refresh is supported via grant_type=refresh_token.

Dynamic client registration example:

curl -s http://localhost:8787/register \
  -H "Content-Type: application/json" \
  -d '{"client_name":"my-mcp-client","redirect_uris":["http://localhost:3000/callback"],"scope":"notion.read notion.write"}'

MCP Endpoint

POST /mcp (Streamable HTTP)
GET /mcp returns 405 (only POST is supported)

Headers:

Authorization: Bearer <access_token>
MCP-Protocol-Version: 2025-11-25 (optional; supported: 2025-11-25, 2025-06-18, 2025-03-26)
Accept: application/json, text/event-stream

OAuth metadata:

/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server
POST /register (dynamic client registration)

Tool Surface

All tools validate inputs with JSON Schema and return JSON-encoded results.

Tool	Scope	Purpose
`notion.search`	`notion.read`	Search pages/databases
`notion.get_page`	`notion.read`	Retrieve a page
`notion.get_database`	`notion.read`	Retrieve a database/data source
`notion.query_database`	`notion.read`	Query database/data source rows
`notion.create_page`	`notion.write`	Create a page
`notion.update_page`	`notion.write`	Update page properties
`notion.append_block`	`notion.write`	Append blocks
`notion.list_users`	`notion.admin`	Governance: list users
`notion.whoami`	`notion.admin`	Governance: integration identity

JSON Schemas

`notion.search`

Input:

{
  "type": "object",
  "properties": {
    "query": { "type": "string" },
    "filter": { "type": "object", "properties": { "object": { "type": "string", "enum": ["page", "database"] } }, "additionalProperties": false },
    "sort": { "type": "object", "properties": { "direction": { "type": "string", "enum": ["ascending", "descending"] }, "timestamp": { "type": "string", "enum": ["last_edited_time", "created_time"] } }, "additionalProperties": false },
    "page_size": { "type": "integer", "minimum": 1, "maximum": 100 },
    "start_cursor": { "type": "string" }
  },
  "additionalProperties": false
}

Output:

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "object": { "type": "string" },
          "url": { "type": "string" },
          "title": { "type": "string" },
          "last_edited_time": { "type": "string" }
        },
        "required": ["id", "object", "url"]
      }
    },
    "next_cursor": { "type": ["string", "null"] },
    "has_more": { "type": "boolean" }
  },
  "required": ["results", "has_more"]
}

`notion.get_page`

Input:

{
  "type": "object",
  "properties": {
    "page_id": { "type": "string" },
    "include_properties": { "type": "boolean", "default": false }
  },
  "required": ["page_id"],
  "additionalProperties": false
}

Output:

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "url": { "type": "string" },
    "created_time": { "type": "string" },
    "last_edited_time": { "type": "string" },
    "archived": { "type": "boolean" },
    "title": { "type": "string" },
    "properties": { "type": "object" }
  },
  "required": ["id", "url"]
}

`notion.get_database`

Input:

{
  "type": "object",
  "properties": { "database_id": { "type": "string" }, "data_source_id": { "type": "string" } },
  "anyOf": [{ "required": ["database_id"] }, { "required": ["data_source_id"] }],
  "additionalProperties": false
}

Output:

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "title": { "type": "string" },
    "url": { "type": ["string", "null"] },
    "properties": { "type": "object" }
  },
  "required": ["id", "url"]
}

`notion.query_database`

Input:

{
  "type": "object",
  "properties": {
    "database_id": { "type": "string" },
    "data_source_id": { "type": "string" },
    "filter": { "type": "object" },
    "sorts": { "type": "array" },
    "page_size": { "type": "integer", "minimum": 1, "maximum": 100 },
    "start_cursor": { "type": "string" }
  },
  "anyOf": [{ "required": ["database_id"] }, { "required": ["data_source_id"] }],
  "additionalProperties": false
}

Output:

{
  "type": "object",
  "properties": {
    "results": { "type": "array" },
    "next_cursor": { "type": ["string", "null"] },
    "has_more": { "type": "boolean" }
  },
  "required": ["results", "has_more"]
}

`notion.create_page`

Input:

{
  "type": "object",
  "properties": {
    "parent": { "type": "object", "properties": { "database_id": { "type": "string" }, "data_source_id": { "type": "string" }, "page_id": { "type": "string" } }, "additionalProperties": false },
    "properties": { "type": "object" },
    "children": { "type": "array" }
  },
  "required": ["parent", "properties"],
  "additionalProperties": false
}

Output:

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "url": { "type": "string" },
    "created_time": { "type": "string" }
  },
  "required": ["id", "url"]
}

`notion.update_page`

Input:

{
  "type": "object",
  "properties": {
    "page_id": { "type": "string" },
    "properties": { "type": "object" },
    "archived": { "type": "boolean" }
  },
  "required": ["page_id"],
  "additionalProperties": false
}

Output:

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "url": { "type": "string" },
    "archived": { "type": "boolean" }
  },
  "required": ["id", "url"]
}

`notion.append_block`

Input:

{
  "type": "object",
  "properties": {
    "block_id": { "type": "string" },
    "children": { "type": "array" }
  },
  "required": ["block_id", "children"],
  "additionalProperties": false
}

Output:

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "has_more": { "type": "boolean" }
  },
  "required": ["id"]
}

`notion.list_users`

Input:

{
  "type": "object",
  "properties": {
    "page_size": { "type": "integer", "minimum": 1, "maximum": 100 },
    "start_cursor": { "type": "string" }
  },
  "additionalProperties": false
}

Output:

{
  "type": "object",
  "properties": {
    "results": { "type": "array" },
    "next_cursor": { "type": ["string", "null"] },
    "has_more": { "type": "boolean" }
  },
  "required": ["results", "has_more"]
}

`notion.whoami`

Input:

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Output:

{
  "type": "object",
  "properties": {
    "bot_id": { "type": "string" },
    "workspace_id": { "type": "string" },
    "owner": { "type": "object" }
  },
  "required": ["bot_id"]
}

Examples

List tools:

curl -s http://localhost:8787/mcp \
  -H "Authorization: Bearer $MCP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Search pages:

curl -s http://localhost:8787/mcp \
  -H "Authorization: Bearer $MCP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"notion.search","arguments":{"query":"Roadmap","page_size":5}}}'

Create a page in a database:

curl -s http://localhost:8787/mcp \
  -H "Authorization: Bearer $MCP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"notion.create_page","arguments":{"parent":{"database_id":"YOUR_DB_ID"},"properties":{"Name":{"title":[{"text":{"content":"Q1 Plan"}}]}}}}}'

Docker

docker build -t notion-mcp .
docker run --env-file .env -p 8787:8787 notion-mcp

Security Notes

OAuth 2.1 + PKCE enforced for MCP clients.
Token storage is AES-256-GCM encrypted via TOKEN_ENC_KEY.
Access tokens are short-lived; refresh tokens rotate access tokens.
Origin allowlist for browser clients via ALLOWED_ORIGINS.
Rate limiting: defaults are 120 requests/min for /mcp and 30 requests/min for auth endpoints.
If encryption/state keys are not set, they are auto-generated and stored under ./data/ for local dev.

Trade-offs / Next Steps

Notion does not document PKCE support for its own OAuth; PKCE is enforced for MCP clients, and upstream Notion OAuth uses standard code exchange.
Dynamic client registration stores client metadata in the encrypted store; could add client secrets and approval workflows for stricter control.
Tool output is returned as JSON text; could add structured content types once supported.
Add rate limiting, audit logs, and per-tenant encryption keys for stronger governance.
For Notion API version 2025-09-03, prefer data_source_id for database-like operations; database_id is kept for backward compatibility.

Notion Remote MCP Server

Notion Remote MCP Server (OAuth + PKCE)

Quick Start (5 minutes)

OAuth for MCP Clients

MCP Endpoint

Tool Surface

JSON Schemas

`notion.search`

`notion.get_page`

`notion.get_database`

`notion.query_database`

`notion.create_page`

`notion.update_page`

`notion.append_block`

`notion.list_users`

`notion.whoami`

Examples

Docker

Security Notes

Trade-offs / Next Steps

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API