Related Pages

Related topics: Installation, Configuration & Deployment, Tools, API Surface & v2.0 Data Source Migration

Project Overview & System Architecture

Purpose and Scope

The Notion MCP Server is an implementation of a Model Context Protocol (MCP) server that exposes the official Notion API as a set of MCP tools consumable by AI agents such as Claude, Cursor, Zed, and other MCP-compatible clients. The project is distributed as the npm package @notionhq/notion-mcp-server (currently at version 2.3.1 per package.json) and is offered under the MIT license. Source: package.json

Rather than hardcoding individual tool definitions, the server takes a spec-driven approach: an OpenAPI document (scripts/notion-openapi.json) is the single source of truth, and tools are generated at runtime from its paths and operations. This pattern means that adding or modifying Notion API endpoints only requires changes to the OpenAPI spec — no source code updates are needed. Source: CLAUDE.md

Note on maintenance: The README explicitly states that the team is prioritizing the newer, remote-hosted Notion MCP (with OAuth and Markdown-friendly editing tools) and may sunset this local server in the future. This repository is still functional and is the subject of this wiki, but issue/PR activity is limited. Source: README.md

High-Level Architecture

The system is composed of three cooperating layers: an OpenAPI specification, a tool-conversion engine, and an MCP server proxy that handles transport and request dispatch. The flow is summarized in the diagram below.

flowchart TD
    A[scripts/notion-openapi.json<br/>OpenAPI spec] -->|loaded & validated| B[src/init-server.ts<br/>MCPProxy factory]
    B --> C[OpenAPIToMCPConverter<br/>src/openapi-mcp-server/openapi/parser.ts]
    C -->|convertToMCPTools| D[MCPProxy<br/>src/openapi-mcp-server/mcp/proxy.ts]
    D -->|ListTools / CallTool handlers| E[MCP Client<br/>Claude, Cursor, etc.]
    D -->|HttpClient.executeOperation| F[Notion REST API]
    G[Auth template<br/>src/openapi-mcp-server/auth] -->|headers| F

Component responsibilities:

• scripts/notion-openapi.json — Defines every Notion API path, operation, parameter, request body, and response schema. The current spec targets the 2025-09-03 Notion API version, which promoted data sources to the primary abstraction (replacing the old "database" model in v2.0.0). Source: README.md
• OpenAPIToMCPConverter (src/openapi-mcp-server/openapi/parser.ts) — Walks every path/operation in the spec and produces a corresponding MCP tool. Each tool's name is the OpenAPI operationId (e.g., retrieve-a-database); its inputSchema is a JSON Schema derived from the operation's parameters and request body; its returnSchema mirrors the response. The converter also exposes convertToAnthropicTools() and convertToOpenAITools() for clients that consume those vendor-specific tool shapes. Source: src/openapi-mcp-server/openapi/parser.ts
• MCPProxy (src/openapi-mcp-server/mcp/proxy.ts) — Wraps the official @modelcontextprotocol/sdk Server, registers each generated tool, and wires up the ListTools/CallTool request handlers. It annotates tools with readOnlyHint or destructiveHint, attaches a human-readable title (e.g., Retrieve A Database), and serializes the HTTP response back to MCP text content. Source: src/openapi-mcp-server/mcp/proxy.ts
• Auth layer (src/openapi-mcp-server/auth/) — Provides types (AuthTemplate, SecurityScheme, Server, TemplateContext) and a Mustache-based renderer (renderAuthTemplate) that substitutes {{args.NOTION_TOKEN}}-style placeholders into the OpenAPI's security scheme at startup. Source: src/openapi-mcp-server/auth/types.ts, src/openapi-mcp-server/auth/template.ts

Tool Generation and Naming Conventions

Tools are produced through a deterministic pipeline that the maintainers describe as the "key pattern" of the codebase. Source: CLAUDE.md

1. OpenAPIToMCPConverter.convertToMCPTools() iterates over paths and, for every HTTP operation that matches isOperation, calls convertOperationToJsonSchema to merge path/query parameters with the JSON-derived request body into a single object schema.
2. The resulting NewToolMethod (name, description, inputSchema, optional returnSchema) is appended to the tool list.
3. MCPProxy.setupHandlers() registers the tool with the MCP SDK and attaches an annotation block: readOnlyHint is set for safe operations and destructiveHint for mutating ones, while operationIdToTitle converts camelCase identifiers (e.g., createDatabase) into a display title ("Create Database"). Tool names longer than 64 characters are truncated to comply with MCP limits. Source: src/openapi-mcp-server/mcp/proxy.ts

After the v2.0.0 migration to the 2025-09-03 API, the canonical tool surface is 22 tools. Three legacy database tools were renamed: post-database-query → query-data-source, update-a-database → update-a-data-source, and create-a-database → create-a-data-source, with the database_id parameter renamed to data_source_id. Source: README.md

Configuration, Transports, and Known Quirks

The server is launched via the notion-mcp-server binary defined in package.json and supports two authentication mechanisms, both expressed through environment variables. Source: README.md, package.json

The server also supports both stdio (default for local clients) and HTTP/SSE transports (the 3000/mcp endpoint), and can be run from a local checkout using npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server for development. Source: README.md

A few community-reported behaviors are worth knowing:

• Double-serialized parameters. Some MCP clients (notably Cursor and Claude Code) send nested object arguments as JSON strings rather than objects. The proxy mitigates this with a deserializeParams step that walks each parameter and re-parses stringified JSON before dispatch, which unblocks affected clients. Source: src/openapi-mcp-server/mcp/proxy.ts
• Inline comment retrieval. The notion-get-comments tool surfaces a page_id parameter, but inline discussions are technically scoped to a block_id; users needing true inline comments must adapt their workflows. Source: community issue #175
• Guest users are blocked upstream. OAuth-based connections refuse accounts that are workspace guests; this is a Notion API limitation, not a server bug. Source: community issue #227
• Client compatibility. Some clients (e.g., early Gemini CLI builds) have been reported to fail when registering the server; users typically resolve this by ensuring the client targets a recent MCP SDK version. Source: community issue #69

See Also

• Installation & client configuration guide (see README "Installation" section)
• v2.0.0 data source migration notes
• OpenAPI-driven tool generation pattern
• Known community issues and workarounds

Related Pages

Related topics: Project Overview & System Architecture, Known Issues, Limitations & Community Workarounds

Installation, Configuration & Deployment

Overview

The notion-mcp-server is an MCP (Model Context Protocol) server that exposes the Notion API as a set of MCP tools. It is published as the npm package @notionhq/notion-mcp-server (currently at v2.3.1 per package.json) and ships with a CLI binary notion-mcp-server. The server is generated from a single OpenAPI source-of-truth document — scripts/notion-openapi.json — so configuration and deployment largely revolve around (1) obtaining a Notion integration token, (2) wiring that token into an MCP client, and (3) selecting a transport mode. Source: README.md and CLAUDE.md.

[!NOTE]

The README explicitly states that the maintainers are prioritizing the remote "Notion MCP" offering, and this local MCP server repository may be sunset in the future. Issues against the remote service should be filed with Notion support rather than this repository. Source: README.md.

Prerequisites & Notion-Side Setup

Before installing the server, you must create an internal Notion integration and grant it access to the pages you want the LLM to read or modify.

1. Visit https://www.notion.so/profile/integrations and create a new internal integration or reuse an existing one.
2. Copy the secret token (format ntn_**). Optionally scope the integration to Read content** only for a read-only deployment.
3. Connect pages/databases to the integration via the Access tab, or by opening a page → ⋯ → Connect to integration.

Source: README.md. Community issue #227 reports that guest users are blocked from connecting — they receive *"You are a guest, so you cannot connect to Notion MCP"*. Workspace owners must upgrade guest accounts to full members before the token will work.

Installation Methods

npm (recommended)

The package can be launched on-demand via npx or installed as a global binary:

npx -y @notionhq/notion-mcp-server

A global install exposes the notion-mcp-server executable declared in package.json:

"bin": { "notion-mcp-server": "bin/cli.mjs" }

Source: package.json.

Local development install

For contributors, the workflow described in README.md is:

npm install
npm run build      # tsc -build && node scripts/build-cli.js
npm test           # NODE_ENV=test vitest run
npm link           # create global symlink for local MCP-client testing

Source: package.json and README.md. The CLAUDE.md file confirms that the architecture flows from scripts/notion-openapi.json → src/init-server.ts → src/openapi-mcp-server/openapi/parser.ts → src/openapi-mcp-server/mcp/proxy.ts → src/openapi-mcp-server/client/http-client.ts. Source: CLAUDE.md.

Configuration

The server reads authentication configuration from environment variables and optionally a custom OpenAPI header template. The following table summarizes every supported configuration knob:

[!NOTE]

Community issue #69 reports compatibility problems when wiring the server into Gemini-CLI. Using OPENAPI_MCP_HEADERS instead of NOTION_TOKEN is one workaround when an MCP client forwards headers differently than expected. Source: README.md.

Cursor / Claude Desktop configuration

Add the following to .cursor/mcp.json or ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

For Zed, the equivalent key is context_servers inside settings.json. Source: README.md.

Tool annotations and JSON deserialization

The MCPProxy.setupHandlers() method in src/openapi-mcp-server/mcp/proxy.ts enriches each auto-generated tool with annotations such as readOnlyHint or destructiveHint, and a human-friendly title derived from the OpenAPI operationId. Source: src/openapi-mcp-server/mcp/proxy.ts. This corresponds to the v2.1.0 release notes that introduced *"tool annotations for improved LLM tool understanding"*.

The same handler runs a deserializeParams() pass before executing each tool call. This is a defensive fix for MCP clients that double-serialize nested JSON parameters (referenced as issue #176 in source comments). Source: src/openapi-mcp-server/mcp/proxy.ts.

Deployment Modes

Local stdio (default)

The simplest deployment: the MCP client spawns the server as a subprocess over stdio. No network exposure is required. This is the mode used by npx -y @notionhq/notion-mcp-server and matches the command/args JSON in client configs. Source: README.md.

SSE / Streamable HTTP (hosted)

The README documents running the server behind an Express endpoint at http://<host>:3000/mcp. The express and node-fetch dependencies in package.json support this transport. Use this mode when multiple clients share a single server instance or when the client cannot spawn local processes. Source: README.md.

Custom OpenAPI builds

Because every tool is derived from scripts/notion-openapi.json, deployments that need to expose additional endpoints (or hide existing ones) only need to modify that file — no source changes are required. The OpenAPIToMCPConverter in src/openapi-mcp-server/openapi/parser.ts walks every path/operation and converts it to an MCP tool named after operationId. Notable behaviors include:

• format: binary parameters are automatically rewritten as format: uri-reference with the description *"absolute paths to local files"*. Source: src/openapi-mcp-server/openapi/parser.ts. Community issue #191 tracks the related feature request for local file uploads.
• Tool names longer than 64 characters are truncated; display titles are produced by operationIdToTitle(). Source: src/openapi-mcp-server/mcp/proxy.ts.
• Inline schemas with oneOf/const discriminators are preserved so that the Notion-2025-09-03 *data-source* parents (which replaced database_id parents in v2.0.0) are correctly described to the LLM. Source: src/openapi-mcp-server/openapi/parser.ts and README.md.

Common Failure Modes

• guest users blocked — see issue #227; upgrade the account to a workspace member.
• notion-get-comments returns no inline discussions — the OpenAPI spec parameter is named block_id even though the MCP tool surfaces it as page_id (issue #175). Document this discrepancy when prompting the LLM to fetch inline comments.
• No database_id parameter on query/update tools — v2.0.0 removed these in favor of data_source_id. Update any hardcoded prompts to use query-data-source / update-a-data-source. Source: README.md.
• Nested JSON arrives as escaped strings — should already be handled by deserializeParams() in the proxy. Source: src/openapi-mcp-server/mcp/proxy.ts.

See Also

• Architecture & Tool Generation
• OpenAPI to MCP Conversion Reference
• Authentication & OAuth Flows
• Troubleshooting & FAQ

Related Pages

Related topics: Project Overview & System Architecture, Known Issues, Limitations & Community Workarounds

Tools, API Surface & v2.0 Data Source Migration

Overview

The Notion MCP Server exposes the Notion API as a set of discoverable MCP tools. Every tool the server advertises is generated automatically from a single source of truth: the OpenAPI specification checked in at scripts/notion-openapi.json. As stated in CLAUDE.md, "Tools are auto-generated from the spec - no code changes needed elsewhere" when adding new endpoints.

The current published release is v2.3.1 per package.json, and v2.0.0 introduced a breaking migration to Notion's API version 2025-09-03, which elevated data sources to the primary abstraction for databases. As a result, the public tool surface changed from 19 tools (v1.x) to 22 tools (v2.0+) according to README.md.

Note from maintainers (README.md): A remote "Notion MCP" with OAuth and Markdown-aware editing has been introduced. Active support is being prioritized on the remote server, and this local repository may be sunset in the future.

Tool Generation Pipeline

Tools are produced by walking the OpenAPI document and converting each operation into an MCP tool definition. The conversion logic lives in OpenAPIToMCPConverter, which exposes three output formats via convertToMCPTools(), convertToOpenAITools(), and convertToAnthropicTools().

flowchart LR
    A[scripts/notion-openapi.json] --> B[OpenAPIToMCPConverter]
    B --> C[Tool definitions<br/>inputSchema + returnSchema]
    C --> D[MCPProxy.setupHandlers]
    D --> E[MCP ListTools response]
    E --> F[CallToolRequest dispatch]
    F --> G[HttpClient → Notion API]

Key behaviors from parser.ts:

• Name source: Tool names come from the OpenAPI operationId (e.g., retrieve-a-database).
• Schema generation: convertOperationToJsonSchema() merges path/query/header parameters and the JSON requestBody into a single inputSchema with a $defs section built from components.schemas.
• Binary handling: Any format: binary schema is rewritten to format: uri-reference with a description noting "absolute paths to local files", anticipating local file uploads.
• Reference resolution: $ref values are resolved recursively with cycle detection; unresolved references fall back to a $defs pointer and a description.

Registration is handled in proxy.ts inside MCPProxy.setupHandlers():

• Naming: Each tool is exposed as ${apiName}-${method.name} and truncated to 64 characters for display.
• Annotations: Read/write hints are derived from the HTTP verb: GET operations are marked readOnlyHint: true; all other methods are marked destructiveHint: true. A human-readable title is generated via operationIdToTitle().
• Parameter tolerance: deserializeParams() (added in v2.1.0 per the release notes) auto-parses stringified JSON values to handle MCP clients that double-serialize nested objects — a fix tracked under issue #176 referenced in the proxy source.

v2.0 Data Source Migration

The v2.0 release aligns the MCP tool surface with Notion's new data source model. The following table summarizes the breaking changes documented in README.md:

The README also notes: "retrieve-a-database is still available and returns database metadata including the list of data source IDs. Use retrieve-a-data-source to get the schema and properties of a specific data source." This addresses community issue #87, where users reported the inability to query a Notion database with structured filters and sorts; query-data-source now fills that gap.

Migration impact: No client code changes are required because MCP tools are discovered dynamically on server start. Users that hardcoded tool names in prompts or scripts need only the renames listed above.

Known Limitations & Community-Reported Issues

Several recurring community threads shape the practical boundaries of the current API surface:

• Inline comment retrieval (#175): The notion-get-comments tool exposes page_id, but the Notion API requires block_id for inline discussions. This is a parameter-shape mismatch in the underlying OpenAPI definition that the auto-generator faithfully propagates.
• Local file uploads (#191): Although the parser pre-rewrites binary fields to uri-reference, end-to-end support for uploading local image and file paths through the MCP tool surface is still an open feature request.
• Guest user access (#227): Guests cannot connect to the Notion MCP via OAuth. This is a workspace-level restriction on the Notion side rather than a server bug, but it materially affects freelancers and contractors.
• Client compatibility (#69): Gemini-CLI users have reported errors when registering the Notion MCP. Such failures are typically mitigated by ensuring the NOTION_TOKEN (or OPENAPI_MCP_HEADERS) environment variable is set and that the client supports the server's transport, as documented in README.md.

When troubleshooting, the HttpClient and auth types modules govern request construction, header injection, and security scheme templating, so issues with missing headers or authentication almost always trace back to environment configuration rather than the generated tools themselves.

See Also

• README.md — Installation, configuration, and v2.0 migration guide
• CLAUDE.md — Architecture overview and contributor guidance
• Notion MCP remote server announcement — OAuth-based successor recommended by maintainers
• Notion API reference — Underlying REST API surface

Related Pages

Related topics: Installation, Configuration & Deployment, Tools, API Surface & v2.0 Data Source Migration

Known Issues, Limitations & Community Workarounds

Overview

This page catalogs the most prominent limitations, defects, and workarounds reported both in the source code and in community discussions around the notion-mcp-server project. It is intended as a quick reference for integrators and contributors who need to understand why certain Notion API behaviors cannot be performed through the local MCP server, and which community-reported issues have been mitigated versus which remain open.

A critical piece of context: the local notion-mcp-server repository is in maintenance mode. The README explicitly states that the team is "prioritizing, and only providing active support for, Notion MCP (remote)" and that this local repository "may [be] sunset in the future." Source: README.md:1-15. Issues filed against this repository may therefore be addressed only in the remote product.

Project Status & Deprecation Notice

The project's primary distribution (@notionhq/notion-mcp-server v2.3.1 per package.json) still ships, but the README warns users to migrate to the remote Notion MCP for OAuth-based installation and AI-agent-optimized tools. Source: package.json:2-22, README.md:1-15. The implication for issue triage is significant: many "bugs" reported against the local server (e.g. #69 Gemini-CLI errors, #227 guest-user lockout) stem from differences between the local stdio/HTTP server and the remote product, and the maintainers redirect users to Notion support for them.

Version 2.0.0 Breaking Changes (Data Source Migration)

The largest cluster of breaking changes in the project's history accompanies the migration to the Notion API 2025-09-03 version, which promotes data sources as the primary database abstraction. Source: README.md:23-58.

Three legacy tools were removed, and three parameters changed. The table below summarizes the migration path and the only configuration action an integrator must take:

retrieve-a-database remains available and returns metadata including the list of data source IDs; integrators should chain it with retrieve-a-data-source to obtain the schema of a specific source. Source: README.md:54-58. The total tool count moved from 19 to 22. Because the OpenAPI spec (scripts/notion-openapi.json) is the single source of truth and the converter generates MCP tools dynamically, no manual code edits are required during migration. Source: CLAUDE.md:5-23.

Tool-Generation & Bug-Mitigation Pipeline

The architecture surfaces bugs quickly because tools are not hand-written — they are auto-derived from the OpenAPI document. Source: CLAUDE.md:13-23.

flowchart LR
    A[scripts/notion-openapi.json] --> B[src/init-server.ts]
    B --> C[OpenAPIToMCPConverter]
    C --> D[MCPProxy.setupHandlers]
    D --> E[Tool Registration]
    F[MCP Client Request] --> G[deserializeParams]
    G --> H[HttpClient.executeOperation]
    H --> I[Notion API]

Two notable mitigations are visible in this pipeline:

• Tool annotations: Released in v2.1.0 (PR #169), each tool now exposes readOnlyHint or destructiveHint plus a human-friendly title derived from the operationId, helping LLMs avoid destructive operations. Source: src/openapi-mcp-server/mcp/proxy.ts:1-40.
• Double-serialization workaround: Some MCP clients (Cursor, Claude Code) pre-serialize nested object parameters as JSON strings, producing invalid requests. deserializeParams recursively detects JSON-shaped strings and parses them before forwarding to the HTTP client. Source: src/openapi-mcp-server/mcp/proxy.ts:42-80. This resolves the bug described in community issue #176.

Community-Reported Limitations

Several limitations recur in the community and cannot be fully fixed inside the local server:

• Local file upload is unsupported (issue #191, 12 comments). The OpenAPI parser maps format: binary parameters to format: uri-reference and rewords the description to "absolute paths to local files," but the actual file-upload endpoint behavior depends on the upstream Notion API. Source: src/openapi-mcp-server/openapi/parser.ts:24-58.
• Guest users are blocked (issue #227). OAuth-based flows reject guest accounts with the message "You are a guest, so you cannot connect to Notion MCP." This is enforced by the upstream Notion API, not the local server, and the recommended workaround is to request a member upgrade from the workspace owner.
• Gemini-CLI incompatibility (issue #69, 21 comments). Google's Gemini CLI does not negotiate the same MCP handshake that Claude/Cursor use, producing transport errors. The maintainer position is to use a client that supports the standard MCP protocol, or migrate to the remote Notion MCP. Source: README.md:1-15.
• notion-get-comments parameter mismatch (issue #175, 7 comments). The tool exposes page_id even though inline discussions are scoped to a block_id. The OpenAPI spec labels the field generically ("Identifier for a Notion block or page") which confuses LLMs. Source: src/openapi-mcp-server/openapi/parser.ts:60-105. Workaround: pass the block UUID directly.
• No first-class database query tool (issue #87, 5 comments). The search tool returns only a flat result set and cannot filter by property values such as priority or status. The community workaround is to call retrieve-a-data-source to fetch the schema, then iterate query-data-source with compound filters. Source: README.md:54-58.

Configuration & Compatibility Workarounds

For the local server, two environment-variable strategies are documented and both must be set in the MCP client config. Source: README.md:80-130.

• Recommended — set NOTION_TOKEN to the integration secret (e.g. ntn_****).
• Advanced — set OPENAPI_MCP_HEADERS to a JSON string containing Authorization and Notion-Version headers, which lets integrators pin the API version.

For local development, the README documents an npm link workflow that creates a global symlink so Cursor and other clients can run the in-progress build. Source: README.md:130-160. The auth template renderer (renderAuthTemplate) relies on Mustache, with HTML escaping explicitly disabled to keep URLs intact. Source: src/openapi-mcp-server/auth/template.ts:1-20. Any user-defined args are passed through TemplateContext.args, so secrets injected this way should be treated as sensitive. Source: src/openapi-mcp-server/auth/types.ts:1-23.

See Also

• Notion MCP (remote) documentation: <https://developers.notion.com/docs/mcp>
• Issue tracker: <https://github.com/makenotion/notion-mcp-server/issues>
• Release notes: see the GitHub Releases page for v2.0.0, v2.1.0, and v2.3.0 changelogs.

Doramagic Pitfall Log

Found 14 structured pitfall item(s), including 2 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/256

2. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/232

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/309

4. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/310

5. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/306

6. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/307

7. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/298

8. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server

9. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/makenotion/notion-mcp-server/issues/296

10. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server

11. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server

12. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | github_repo:946169991 | https://github.com/makenotion/notion-mcp-server