notion-mcp-server 2.4.4 → 2.5.0

package/README.md

@@ -209,6 +209,8 @@ If you ran a v1.x setup, **nothing in your environment needs to change**. Both e
 | `NOTION_TOKEN` | ✅ Required | Accepts **PATs** (`ntn_…`, recommended) and **Internal Integration secrets** (`secret_…` or `ntn_…`, legacy). Identical handling. |
 | `NOTION_PAGE_ID` | ✅ Optional | Still works as the default parent page for `create_page` / `create_database` when no `parent` is passed. v2 added a clean `missing_parent` validation error instead of v1's crash when neither is provided. |
 | `NOTION_RATE_LIMIT` | ✅ New, optional | Requests per second for the shared limiter. Defaults to `3` (Notion's documented per-integration limit). |
+| `NOTION_ALLOWED_OPERATIONS` | ✅ New, optional | Comma-separated allowlist of operations or group presets (`read`, `write`, `destructive`, plus per-domain groups `pages`, `blocks`, `databases`, `data_sources`, `comments`, `users`, `files`). Unset ⇒ all operations enabled. See [Restricting operations](#restricting-operations). |
+| `NOTION_BLOCKED_OPERATIONS` | ✅ New, optional | Comma-separated blocklist (same token vocabulary). Applied after the allowlist, so a blocked operation is always disabled. |
 | `NOTION_DAILY_LOG_PAGE_ID` | ✅ Optional | Used only by the daily-log MCP prompt. Ignore if you don't call that prompt. |
 
 The only v2 break is the **tool surface itself** — v1's `notion_pages`, `notion_blocks`, `notion_database`, `notion_comments`, `notion_users` are replaced by `notion_execute` and `notion_describe`. Modern MCP clients (Claude Code, Cursor, Claude Desktop) rediscover tools at startup, so they pick up the new surface automatically. If your client hard-codes the v1 tool names, see [MIGRATION.md](./MIGRATION.md) for the rename map.
@@ -219,6 +221,93 @@ A typical v1.x invocation continues to work unchanged:
 NOTION_TOKEN=secret_xxx NOTION_PAGE_ID=abc123... node build/index.js
 ```
 
+### Restricting operations
+
+By default every operation is available. To limit what an agent can do, set
+`NOTION_ALLOWED_OPERATIONS` (an allowlist) and/or `NOTION_BLOCKED_OPERATIONS` (a
+blocklist). Each is a comma-separated list of **tokens**, where a token is either a
+**group preset** or an exact **operation name**.
+
+**Group presets** (one token expands to many operations):
+
+| Token | Expands to |
+| --- | --- |
+| `read` | every non-mutating operation |
+| `write` | every mutating operation |
+| `destructive` | operations whose purpose is removal (marked † below) |
+| `pages` `blocks` `databases` `data_sources` `comments` `users` `files` | every operation in that resource family (read **and** write) |
+
+**All operations** — use any name directly for a precise allow/blocklist. († = also in the `destructive` group.)
+
+| Domain | Read | Write |
+| --- | --- | --- |
+| `pages` | `search_pages` `get_page` `get_page_markdown` | `create_page` `set_page_title` `set_page_property` `set_page_properties` `update_page_markdown` `move_page` `restore_page` `archive_page`† `trash_page`† |
+| `blocks` | `get_block` `get_block_children` | `append_blocks` `update_block` `delete_block`† `batch_mixed_blocks`† |
+| `databases` | `query_database` | `create_database` `update_database` |
+| `data_sources` | `list_data_sources` `get_data_source` | `update_data_source` |
+| `comments` | `list_comments` `get_comment` | `add_page_comment` `add_discussion_comment` `update_comment` `delete_comment`† |
+| `users` | `list_users` `get_user` `get_bot_user` `get_self` | — |
+| `files` | `list_file_uploads` `get_file_upload` | `upload_file` |
+
+Read-only deployment (the most common case):
+
+```json
+{
+  "mcpServers": {
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "notion-mcp-server"],
+      "env": {
+        "NOTION_TOKEN": "ntn_paste_your_token_here",
+        "NOTION_ALLOWED_OPERATIONS": "read"
+      }
+    }
+  }
+}
+```
+
+Allow everything except destructive operations:
+
+```json
+{ "env": { "NOTION_BLOCKED_OPERATIONS": "destructive" } }
+```
+
+Mix presets and individual ops (read everything, plus append blocks and comments):
+
+```json
+{ "env": { "NOTION_ALLOWED_OPERATIONS": "read,append_blocks,add_page_comment" } }
+```
+
+**Rules:** tokens are case-insensitive; unknown tokens are ignored with a warning; the
+blocklist wins on conflict; and if the allowlist is set but resolves to no enabled
+operations (all tokens invalid, or every allowed op also blocked), **all** operations are
+disabled (fail-closed). Disabled operations are hidden from the `notion://operations`
+menu and from `notion_describe`, and `notion_execute` rejects them with
+`operation_not_allowed`.
+
+**Verifying your configuration.** On startup the server prints one line to **stderr**
+(visible in your MCP client's server logs) summarizing what resolved, e.g.:
+
+```text
+Operation access: 16/37 enabled (allow=read; block=(none))
+```
+
+Unknown tokens and a fail-closed allowlist are logged there too. If the count or the
+`allow`/`block` values aren't what you expect, check that line first.
+
+**Limitations** (control is per-operation, not per-parameter):
+
+- The `destructive` group covers operations whose *purpose* is removal (`trash_page`,
+  `archive_page`, `delete_block`, `delete_comment`, `batch_mixed_blocks`). A few *write*
+  operations can also remove content via a parameter — e.g. `update_database` /
+  `update_data_source` accept `in_trash`, and `update_page_markdown` can replace a page
+  body. Blocking `destructive` does **not** disable those write ops. **For a guaranteed
+  no-mutation deployment, use the allowlist** (`NOTION_ALLOWED_OPERATIONS=read`), which
+  excludes every write operation.
+- MCP *prompts* (e.g. the daily-log prompt) may still reference operations you have
+  disabled. The prompt text is unaffected by the allowlist; the underlying operation is
+  still rejected at execution time.
+
 ### Claude Code / Cursor / Claude Desktop
 
 **Claude Code:**

package/build/dispatch/index.js

@@ -1,11 +1,12 @@
 import { z } from "zod";
-import { getOperation, operationNames } from "../operations/registry.js";
+import { getOperation } from "../operations/registry.js";
 import { buildKey, lookup, store } from "./idempotency.js";
 import { mapWithConcurrency } from "./concurrency.js";
 import { rateLimiter } from "./rate-limit.js";
 import { isRetryableErrorCode, withRetry } from "./retry.js";
 import { buildValidationError } from "../utils/learning-error.js";
 import { toErrorEnvelope } from "../utils/error.js";
+import { isOperationAllowed, operationNotAllowedError, enabledOperationNames, } from "../operations/access.js";
 const DEFAULT_CONCURRENCY = 3;
 const MAX_CONCURRENCY = 10;
 function isBatchPayload(payload) {
@@ -16,8 +17,8 @@ function isBatchPayload(payload) {
 function unknownOperationError(name) {
     return {
         code: "unknown_operation",
-        message: `Unknown operation: "${name}". Use notion_describe with a valid operation name, or check the notion://operations resource for the full list.`,
-        fix: `Available operations: ${operationNames().join(", ")}`,
+        message: `Unknown operation: "${name}". Use notion_describe with a valid operation name, or check the notion://operations resource for the available list.`,
+        fix: `Available operations: ${enabledOperationNames().join(", ")}`,
     };
 }
 export async function dispatch(operationName, payload) {
@@ -25,6 +26,9 @@ export async function dispatch(operationName, payload) {
     if (!def) {
         return { ok: false, error: unknownOperationError(operationName) };
     }
+    if (!isOperationAllowed(operationName)) {
+        return { ok: false, error: operationNotAllowedError(operationName) };
+    }
     if (isBatchPayload(payload)) {
         if (!def.batchable) {
             // batch_mixed_blocks looks batch-shaped but uses its own `operations[]`

package/build/operations/access.js

@@ -0,0 +1,125 @@
+import { listOperations } from "./registry.js";
+export const ALLOWED_ENV_VAR = "NOTION_ALLOWED_OPERATIONS";
+export const BLOCKED_ENV_VAR = "NOTION_BLOCKED_OPERATIONS";
+function parseList(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+}
+/** Every domain is a valid group token. Typed so a new OperationDomain is a compile error here until added. */
+const DOMAIN_GROUPS = [
+    "pages",
+    "blocks",
+    "databases",
+    "data_sources",
+    "comments",
+    "users",
+    "files",
+];
+/** Expand a single token to op names, or null if it matches no group and no op. */
+function expandToken(token, ops) {
+    switch (token) {
+        case "read":
+            return ops.filter((o) => o.access === "read").map((o) => o.name);
+        case "write":
+            return ops.filter((o) => o.access === "write").map((o) => o.name);
+        case "destructive":
+            return ops.filter((o) => o.destructive === true).map((o) => o.name);
+        default:
+            if (DOMAIN_GROUPS.includes(token)) {
+                return ops.filter((o) => o.domain === token).map((o) => o.name);
+            }
+            return ops.some((o) => o.name === token) ? [token] : null;
+    }
+}
+/** Pure resolver: (ops, allow, block) -> enabled set. No env / registry access. */
+export function resolveEnabled(ops, allowEnv, blockEnv) {
+    const warnings = [];
+    const expand = (tokens, label) => {
+        const set = new Set();
+        for (const token of tokens) {
+            const names = expandToken(token, ops);
+            if (names === null) {
+                warnings.push(`Unknown ${label} token: "${token}" (ignored)`);
+                continue;
+            }
+            names.forEach((n) => set.add(n));
+        }
+        return set;
+    };
+    const allowSpecified = allowEnv !== undefined && allowEnv.trim() !== "";
+    const allowSet = allowSpecified
+        ? expand(parseList(allowEnv), ALLOWED_ENV_VAR)
+        : new Set(ops.map((o) => o.name));
+    const blockSet = expand(parseList(blockEnv), BLOCKED_ENV_VAR);
+    const enabled = new Set([...allowSet].filter((n) => !blockSet.has(n)));
+    // An allowlist that resolves to nothing executable — every token invalid, or
+    // every allowed op also blocked — is a misconfiguration. Surface it loudly
+    // rather than silently running the server with zero operations enabled.
+    const failedClosed = allowSpecified && enabled.size === 0;
+    return { enabled, warnings, failedClosed };
+}
+// ── Memoized singleton over the real registry + process.env ────────────────
+let cache = null;
+function compute() {
+    const ops = listOperations().map((o) => ({
+        name: o.name,
+        access: o.access,
+        domain: o.domain,
+        destructive: o.destructive,
+    }));
+    const result = resolveEnabled(ops, process.env[ALLOWED_ENV_VAR], process.env[BLOCKED_ENV_VAR]);
+    for (const w of result.warnings) {
+        console.error(`[operation-access] ${w}`);
+    }
+    if (result.failedClosed) {
+        console.error(`[operation-access] ${ALLOWED_ENV_VAR} resolved to zero enabled operations — ALL operations are disabled. Check for unknown tokens, or an allowlist fully cancelled by ${BLOCKED_ENV_VAR}.`);
+    }
+    return result;
+}
+function get() {
+    if (cache)
+        return cache;
+    const result = compute();
+    // Don't memoize a result derived from an unpopulated registry (e.g. if called
+    // before initOperations() ran) — recompute once operations are registered.
+    if (listOperations().length > 0)
+        cache = result;
+    return result;
+}
+export function isOperationAllowed(name) {
+    return get().enabled.has(name);
+}
+/** Enabled op names in registry order. */
+export function enabledOperationNames() {
+    const { enabled } = get();
+    return listOperations()
+        .map((o) => o.name)
+        .filter((n) => enabled.has(n));
+}
+export function enabledOperations() {
+    const { enabled } = get();
+    return listOperations().filter((o) => enabled.has(o.name));
+}
+export function accessSummary() {
+    return {
+        enabled: get().enabled.size,
+        total: listOperations().length,
+        allow: process.env[ALLOWED_ENV_VAR]?.trim() || "(all)",
+        block: process.env[BLOCKED_ENV_VAR]?.trim() || "(none)",
+    };
+}
+/** Clear the memoized result so the next call re-reads env. Used by tests. */
+export function configureOperationAccess() {
+    cache = null;
+}
+export function operationNotAllowedError(name) {
+    return {
+        code: "operation_not_allowed",
+        message: `Operation "${name}" is disabled by server configuration.`,
+        fix: `Enabled operations: ${enabledOperationNames().join(", ")}`,
+    };
+}

package/build/operations/blocks.js

@@ -27,6 +27,8 @@ const AppendBlocksParams = z
 });
 register({
     name: "append_blocks",
+    access: "write",
+    domain: "blocks",
     description: "Append children to a page or block. Use markdown for prose content.",
     batchable: true,
     schema: AppendBlocksParams,
@@ -99,6 +101,8 @@ const GetBlockParams = z.object({
 });
 register({
     name: "get_block",
+    access: "read",
+    domain: "blocks",
     description: "Retrieve a single block by ID (metadata + type-specific body). For its children, use get_block_children.",
     batchable: true,
     schema: GetBlockParams,
@@ -123,6 +127,8 @@ const GetBlockChildrenParams = z.object({
 });
 register({
     name: "get_block_children",
+    access: "read",
+    domain: "blocks",
     description: "List child blocks under a page or block, paginated.",
     batchable: false,
     schema: GetBlockChildrenParams,
@@ -191,6 +197,8 @@ const UpdateBlockParams = z
 });
 register({
     name: "update_block",
+    access: "write",
+    domain: "blocks",
     description: "Update an existing block's content. Pass `markdown` for prose blocks (parsed locally to a single block), or `data` for structured updates such as toggling a to_do's `checked` field or setting a code block's language.",
     batchable: true,
     schema: UpdateBlockParams,
@@ -234,6 +242,9 @@ register({
 const DeleteBlockParams = z.object({ block_id: z.string(), verbose: VERBOSE });
 register({
     name: "delete_block",
+    access: "write",
+    domain: "blocks",
+    destructive: true,
     description: "Archive (soft-delete) a block.",
     batchable: true,
     schema: DeleteBlockParams,
@@ -272,6 +283,9 @@ const BatchMixedBlocksParams = z.object({
 });
 register({
     name: "batch_mixed_blocks",
+    access: "write",
+    domain: "blocks",
+    destructive: true,
     description: "Run a sequence of mixed block operations (append/update/delete) in order. Uses a non-standard envelope: { operations: [{ op: \"append\"|\"update\"|\"delete\", ... }] } — NOT the universal { items: [...] } batch envelope. For pure single-op batches, prefer the items[] form on append_blocks / update_block / delete_block.",
     batchable: false,
     schema: BatchMixedBlocksParams,

package/build/operations/comments.js

@@ -30,6 +30,8 @@ const ListCommentsParams = z.object({
 });
 register({
     name: "list_comments",
+    access: "read",
+    domain: "comments",
     description: "List comments on a page or block. Pass paginate:true to auto-walk all pages.",
     batchable: false,
     schema: ListCommentsParams,
@@ -77,6 +79,8 @@ const AddPageCommentParams = z
 });
 register({
     name: "add_page_comment",
+    access: "write",
+    domain: "comments",
     description: "Add a top-level comment to a page. Body can be plain text or markdown.",
     batchable: true,
     schema: AddPageCommentParams,
@@ -111,6 +115,8 @@ const AddDiscussionCommentParams = z
 });
 register({
     name: "add_discussion_comment",
+    access: "write",
+    domain: "comments",
     description: "Reply to an existing discussion thread. Body can be plain text or markdown.",
     batchable: true,
     schema: AddDiscussionCommentParams,
@@ -133,6 +139,8 @@ const GetCommentParams = z.object({
 });
 register({
     name: "get_comment",
+    access: "read",
+    domain: "comments",
     description: "Retrieve a single comment by ID.",
     batchable: true,
     schema: GetCommentParams,
@@ -158,6 +166,8 @@ const UpdateCommentParams = z
 });
 register({
     name: "update_comment",
+    access: "write",
+    domain: "comments",
     description: "Replace a comment's body. Pass markdown or rich_text (not both).",
     batchable: true,
     schema: UpdateCommentParams,
@@ -179,6 +189,9 @@ const DeleteCommentParams = z.object({
 });
 register({
     name: "delete_comment",
+    access: "write",
+    domain: "comments",
+    destructive: true,
     description: "Delete a comment.",
     batchable: true,
     schema: DeleteCommentParams,

package/build/operations/data-sources.js

@@ -13,6 +13,8 @@ const ListDataSourcesParams = z.object({
 });
 register({
     name: "list_data_sources",
+    access: "read",
+    domain: "data_sources",
     description: "List data sources under a database. Use this before query_database when targeting multi-source databases.",
     batchable: false,
     schema: ListDataSourcesParams,
@@ -38,6 +40,8 @@ const GetDataSourceParams = z.object({
 });
 register({
     name: "get_data_source",
+    access: "read",
+    domain: "data_sources",
     description: "Retrieve a single data source's schema (its property definitions and parent database).",
     batchable: true,
     schema: GetDataSourceParams,
@@ -60,6 +64,8 @@ const UpdateDataSourceParams = z.object({
 });
 register({
     name: "update_data_source",
+    access: "write",
+    domain: "data_sources",
     description: "Update a data source's schema (properties, title, icon). For database-level metadata use update_database.",
     batchable: true,
     schema: UpdateDataSourceParams,

package/build/operations/databases.js

@@ -45,6 +45,8 @@ function resolveParent(parent) {
 }
 register({
     name: "create_database",
+    access: "write",
+    domain: "databases",
     description: "Create a new database. Properties is a map of name → property-type definition.",
     batchable: true,
     schema: CreateDatabaseParams,
@@ -138,6 +140,8 @@ const QueryDatabaseParams = z
 });
 register({
     name: "query_database",
+    access: "read",
+    domain: "databases",
     description: "Query a database with optional filter and sorts. Results are page objects.",
     batchable: false,
     schema: QueryDatabaseParams,
@@ -304,6 +308,8 @@ const UpdateDatabaseParams = z.object({
 });
 register({
     name: "update_database",
+    access: "write",
+    domain: "databases",
     description: "Update database-level metadata (title, description, icon, cover, is_inline, is_locked, in_trash). For schema/property changes, use update_data_source.",
     batchable: true,
     schema: UpdateDatabaseParams,

package/build/operations/files.js

@@ -121,6 +121,8 @@ const UploadFileParams = z.object({
 });
 register({
     name: "upload_file",
+    access: "write",
+    domain: "files",
     description: "Upload a file via Notion's file_uploads API. Handles single-part (one create + one send) and multi-part (create + N sends + complete) transparently.\n\nSource shapes:\n  • Base64 bytes: `source: { type: \"base64\", data: \"<b64 string>\" }`\n  • Public URL:   `source: { type: \"url\", url: \"https://example.com/file.pdf\" }` (the server fetches it server-side).\n\n`mode` defaults to \"single\"; only pass \"multi\" for files larger than ~5MB.",
     batchable: false,
     schema: UploadFileParams,
@@ -205,6 +207,8 @@ const ListFileUploadsParams = z.object({
 });
 register({
     name: "list_file_uploads",
+    access: "read",
+    domain: "files",
     description: "List file uploads, optionally filtered by status.",
     batchable: false,
     schema: ListFileUploadsParams,
@@ -231,6 +235,8 @@ const GetFileUploadParams = z.object({
 });
 register({
     name: "get_file_upload",
+    access: "read",
+    domain: "files",
     description: "Retrieve a single file upload by ID.",
     batchable: true,
     schema: GetFileUploadParams,

package/build/operations/pages.js

@@ -56,6 +56,8 @@ const CreatePageParams = z
 });
 register({
     name: "create_page",
+    access: "write",
+    domain: "pages",
     description: "Create a new Notion page. Body can be markdown (recommended) or structured blocks.",
     batchable: true,
     schema: CreatePageParams,
@@ -123,6 +125,8 @@ const SetPageTitleParams = z.object({
 });
 register({
     name: "set_page_title",
+    access: "write",
+    domain: "pages",
     description: "Rename a page. Updates the page's title property.",
     batchable: true,
     schema: SetPageTitleParams,
@@ -170,6 +174,8 @@ const SetPagePropertyParams = z.preprocess(wrapTitleShorthand, z.object({
 }));
 register({
     name: "set_page_property",
+    access: "write",
+    domain: "pages",
     description: "Set one property on one page. For batch updates use items[].",
     batchable: true,
     schema: SetPagePropertyParams,
@@ -220,6 +226,8 @@ const SetPagePropertiesParams = z.preprocess(wrapTitleShorthandInProperties, z.o
 }));
 register({
     name: "set_page_properties",
+    access: "write",
+    domain: "pages",
     description: "Set multiple properties on one page in a single API call. Use set_page_property for one-off updates.",
     batchable: true,
     schema: SetPagePropertiesParams,
@@ -260,6 +268,9 @@ const archivePageHandler = tryHandler(async ({ page_id, verbose }) => {
 });
 register({
     name: "archive_page",
+    access: "write",
+    domain: "pages",
+    destructive: true,
     description: "Move a page to trash. Reversible via restore_page. Alias: trash_page.",
     batchable: true,
     schema: PageIdParams,
@@ -269,6 +280,9 @@ register({
 });
 register({
     name: "trash_page",
+    access: "write",
+    domain: "pages",
+    destructive: true,
     description: "Alias of archive_page (2025-09-03 surface naming). Moves a page to trash.",
     batchable: true,
     schema: PageIdParams,
@@ -278,6 +292,8 @@ register({
 });
 register({
     name: "restore_page",
+    access: "write",
+    domain: "pages",
     description: "Restore a page previously moved to trash.",
     batchable: true,
     schema: PageIdParams,
@@ -310,6 +326,8 @@ const SearchPagesParams = z.object({
 });
 register({
     name: "search_pages",
+    access: "read",
+    domain: "pages",
     description: "Search pages and databases by title. Title-only; does NOT search page body content. Pass paginate:true to auto-walk all pages.",
     batchable: false,
     schema: SearchPagesParams,
@@ -360,6 +378,8 @@ const GetPageParams = z.object({
 });
 register({
     name: "get_page",
+    access: "read",
+    domain: "pages",
     description: "Retrieve a page's metadata and (optionally) properties. No body blocks — use get_block_children for those. Pass `include_properties: true` to also return a flattened properties map.",
     batchable: true,
     schema: GetPageParams,
@@ -383,6 +403,8 @@ const MovePageParams = z.object({
 });
 register({
     name: "move_page",
+    access: "write",
+    domain: "pages",
     description: "Move a page to a new parent without recreating it. Preserves the page's blocks, properties, and comments. The destination uses `parent` — same field name as create_page.",
     batchable: true,
     schema: MovePageParams,
@@ -422,6 +444,8 @@ const GetPageMarkdownParams = z.object({
 });
 register({
     name: "get_page_markdown",
+    access: "read",
+    domain: "pages",
     description: "Return a page's body as Notion-rendered markdown. Server-side conversion; round-trips with update_page_markdown.",
     batchable: true,
     schema: GetPageMarkdownParams,
@@ -451,6 +475,8 @@ const UpdatePageMarkdownParams = z.object({
 });
 register({
     name: "update_page_markdown",
+    access: "write",
+    domain: "pages",
     description: "Replace (or insert into) a page's body using Notion's server-side markdown renderer. Skip the local remark pipeline.",
     batchable: true,
     schema: UpdatePageMarkdownParams,

package/build/operations/users.js

@@ -25,6 +25,8 @@ const ListUsersParams = z.object({
 });
 register({
     name: "list_users",
+    access: "read",
+    domain: "users",
     description: "List all users in the workspace. Requires the integration to have 'Read user information' capability enabled. Pass paginate:true to auto-walk all pages.",
     batchable: false,
     schema: ListUsersParams,
@@ -64,6 +66,8 @@ register({
 const GetUserParams = z.object({ user_id: z.string(), verbose: VERBOSE });
 register({
     name: "get_user",
+    access: "read",
+    domain: "users",
     description: "Get one user by ID. Requires 'Read user information' capability.",
     batchable: true,
     schema: GetUserParams,
@@ -85,6 +89,8 @@ const getBotUserHandler = tryHandler(async ({ verbose }) => {
 });
 register({
     name: "get_bot_user",
+    access: "read",
+    domain: "users",
     description: "Get the integration's bot user. Always works without extra capabilities. Alias: get_self.",
     batchable: false,
     schema: GetBotUserParams,
@@ -93,6 +99,8 @@ register({
 });
 register({
     name: "get_self",
+    access: "read",
+    domain: "users",
     description: "Alias of get_bot_user. Returns the integration's bot user (i.e. the identity behind the current token).",
     batchable: false,
     schema: GetBotUserParams,

package/build/tools/index.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { server } from "../server/index.js";
-import { initOperations, getOperation, listOperations, operationNames } from "../operations/index.js";
+import { initOperations, getOperation } from "../operations/index.js";
+import { isOperationAllowed, operationNotAllowedError, enabledOperationNames, enabledOperations, accessSummary, } from "../operations/access.js";
 import { dispatch } from "../dispatch/index.js";
 import { emitJsonSchema } from "../schema/emit.js";
 import { registerAllPrompts } from "../prompts/index.js";
@@ -74,10 +75,13 @@ export async function registerAllTools() {
                 error: {
                     code: "unknown_operation",
                     message: `Unknown operation: "${operation}".`,
-                    fix: `Available: ${operationNames().join(", ")}`,
+                    fix: `Available: ${enabledOperationNames().join(", ")}`,
                 },
             });
         }
+        if (!isOperationAllowed(operation)) {
+            return errorContent({ ok: false, error: operationNotAllowedError(operation) });
+        }
         return jsonContent({
             name: def.name,
             description: def.description,
@@ -102,6 +106,8 @@ export async function registerAllTools() {
         ],
     }));
     registerAllPrompts();
+    const s = accessSummary();
+    console.error(`Operation access: ${s.enabled}/${s.total} enabled (allow=${s.allow}; block=${s.block})`);
 }
 function renderOperationsIndex() {
     const lines = [
@@ -112,9 +118,14 @@ function renderOperationsIndex() {
         "| Operation | Batchable | Description |",
         "| --- | --- | --- |",
     ];
-    for (const def of listOperations()) {
+    for (const def of enabledOperations()) {
         lines.push(`| \`${def.name}\` | ${def.batchable ? "yes" : "no"} | ${def.description} |`);
     }
+    // Only document the query_database filter DSL when that op is actually enabled —
+    // otherwise the menu advertises a disabled operation.
+    if (!isOperationAllowed("query_database")) {
+        return lines.join("\n");
+    }
     lines.push("", "## `query_database` WHERE DSL", "");
     lines.push("`query_database.where` is a compact DSL that compiles to the Notion filter object. AND-by-default at the top level; nest `and`/`or`/`not` (case-insensitive — `AND`/`OR`/`NOT` also work) for boolean groups, prefix scalars with `__type` to force the property type, or fall back to raw `filter` for anything the DSL can't express.", "", "Common shapes:", "", "```jsonc", "// Single equality (property type inferred from value, or from data source schema via __type):", "{ \"where\": { \"Status\": \"Open\" } }", "", "// AND of multiple properties (top-level keys are implicit AND):", "{ \"where\": { \"Status\": \"Done\", \"Done\": true } }", "", "// Explicit operator on one property:", "{ \"where\": { \"Priority\": { \"gte\": 3 } } }", "", "// Boolean groups (lowercase or uppercase — both work):", "{ \"where\": { \"or\": [ { \"Status\": \"Open\" }, { \"Status\": \"In progress\" } ] } }", "{ \"where\": { \"and\": [ { \"Status\": \"Done\" }, { \"Priority\": { \"gte\": 5 } } ] } }", "{ \"where\": { \"not\": { \"Status\": \"Done\" } } }", "", "// in / notIn fan out to OR / AND of equals:", "{ \"where\": { \"Status\": { \"in\": [\"Open\", \"In progress\"] } } }", "", "// Force property type when value shape is ambiguous (e.g. a string that's actually a multi_select tag):", "{ \"where\": { \"Tags\": { \"__type\": \"multi_select\", \"eq\": \"alpha\" } } }", "{ \"where\": { \"Created\": { \"__type\": \"date\", \"on_or_after\": \"2026-01-01\" } } }", "```", "", "If a column is literally named `and`/`or`/`not`, wrap it as an operator object (e.g. `{ \"and\": { \"__type\": \"select\", \"eq\": \"x\" } }`) so it isn't parsed as a combinator. For anything the DSL can't express, pass `filter` (raw Notion filter object) instead of `where`.");
     return lines.join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notion-mcp-server",
-  "version": "2.4.4",
+  "version": "2.5.0",
   "type": "module",
   "bin": {
     "notion-mcp-server": "build/index.js"
@@ -49,6 +49,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.13.10",
     "shx": "^0.3.4",
     "typescript": "^5.8.2",