Notion MCP Nexus Gateway

This server acts as the integration bridge for allowing Large Language Models (LLMs) to effectively interact with Notion workspaces through the Notion API. A core feature is the preemptive transformation of retrieved content into Markdown structure, which significantly curtails the context window size required for LLM processing, thereby enhancing interaction efficiency and reducing operational costs.

Initialization Procedure

Refer to the following external guides for comprehensive setup instructions:

• English Resource: https://dev.to/suekou/operating-notion-via-claude-desktop-using-mcp-c0h

• Japanese Resource: https://qiita.com/suekou/items/44c864583f5e3e6325d9

• Establish a Notion Integration Credential:

• Navigate to the Notion Integrations Management portal.

• Initiate a "New Integration" setup.

• Assign a descriptive label and grant the necessary operational permissions (e.g., read/write content access).

• Acquire the Authorization Token:

• Extract the generated "Internal Integration Token" associated with your new credential.

• This secret string is mandatory for authenticating API requests.

• Workspace Authorization:

• Open the specific Notion page or database intended for access in your Notion client.

• Utilize the top-right '···' menu option.

• Select the 'Connections' setting and explicitly link the integration created in step 1.

• Configure the Consumer Application (e.g., Claude Desktop): Update your configuration file (claude_desktop_config.json) as follows:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

Alternatively, if running locally after compilation:

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["your-built-file-path"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

Environment Variables (Configuration Directives)

• NOTION_API_TOKEN (Mandatory): The secret key obtained from your Notion integration for API access.
• NOTION_MARKDOWN_CONVERSION: Set this to "true" to activate the experimental feature that converts Notion object responses into Markdown. This drastically reduces the token load during content consumption but might interfere with operations requiring precise structural fidelity (like editing).

Execution Parameters (CLI Arguments)

• --enabledTools: A comma-delimited string specifying precisely which operational endpoints should be exposed (e.g., "notion_retrieve_page,notion_query_database"). If omitted, all available functions are activated.

Read-only invocation example (ready for copy-pasting):

node build/index.js --enabledTools=notion_retrieve_block,notion_retrieve_block_children,notion_retrieve_page,notion_query_database,notion_retrieve_database,notion_search,notion_list_all_users,notion_retrieve_user,notion_retrieve_bot_user,notion_retrieve_comments

Advanced Tuning: Content Formatting Control

By default, the server delivers raw JSON structures. To leverage the token-saving Markdown mechanism, you must enable it via the environment variable AND request the format during tool invocation. This formatting is applied only when the environment variable is true.

Example configuration enabling Markdown transformation:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token",
        "NOTION_MARKDOWN_CONVERSION": "true"
      }
    }
  }
}

When activated, you control the output format via the request's format parameter:

• Setting format to "markdown": Optimizes output for LLM comprehension and human review.
• Setting format to "json": Preserves the native Notion data structure, necessary for operations where the exact schema integrity is paramount (e.g., updates).

Debugging Common Issues

Encountering authorization failures usually points to one of these configuration errors:

1. Verify that the Notion integration possesses the requisite scopes (permissions).
2. Confirm that the integration has been explicitly added as a collaborator to the targeted pages/databases.
3. Double-check the integrity of the NOTION_API_TOKEN within claude_desktop_config.json.

Source Code Architecture Overview

The project maintains a modular structure for clarity and ease of maintenance:

./
├── src/
│   ├── index.ts              # Main execution entry and argument parser
│   ├── client/
│   │   └── index.ts          # Abstraction layer (NotionClientWrapper) for API calls
│   ├── server/
│   │   └── index.ts          # MCP request handling and server bootstrap
│   ├── types/
│   │   ├── index.ts          # Unified type exports
│   │   ├── args.ts           # Interfaces defining tool input parameters
│   │   ├── common.ts         # Core definitions (IDs, RichText structure)
│   │   ├── responses.ts      # Type definitions mirroring Notion API replies
│   │   └── schemas.ts        # Definitions for the MCP tool contract schemas
│   ├── utils/
│   │   └── index.ts          # Helper functions (e.g., tool filtering logic)
│   └── markdown/
│       └── index.ts          # Logic dedicated to JSON-to-Markdown serialization

Component Descriptions

• index.ts (Root): Initiates the application, manages CLI argument parsing, and launches the server process.
• client/: Encapsulates all direct communication with the Notion remote services. The NotionClientWrapper class handles the API interactions.
• server/: Implements the intermediary service that intercepts requests from the client application (Claude) and translates them into calls against the client layer.
• types/: Central repository for all data structure definitions.
• utils/: Houses general-purpose helper routines.
• markdown/: Contains the specialized routines for transforming complex Notion JSON objects into semantically accurate Markdown representations.

Available Operations (Tools)

All functions accept an optional parameter for output formatting:

• format (string, options: "json" or "markdown", default: "markdown"): Directs the response serialization method. Remember, Markdown conversion is contingent on NOTION_MARKDOWN_CONVERSION being set to "true".

• notion_append_block_children

• Action: Attaches supplementary blocks beneath a specified parent container.

• Necessary Parameters:
  • block_id (string): Identifier of the container block.
  • children (array): A collection of block objects to introduce.

• Output: Status report on the newly added blocks.

• notion_retrieve_block

• Action: Fetches metadata for a singular block entity.

• Necessary Parameters:
  • block_id (string): Target block identifier.

• Output: Full descriptive payload of the block.

• notion_retrieve_block_children

• Action: Enumerates the direct descendants of a block.

• Necessary Parameters:
  • block_id (string): Parent block identifier.
• Optional Parameters:
  • start_cursor (string): Token for resuming paginated results.
  • page_size (number, default: 100, max: 100): Count limit per retrieval cycle.

• Output: A list containing the child blocks.

• notion_delete_block

• Action: Permanently eradicates a specified block.

• Necessary Parameters:
  • block_id (string): Identifier of the item to remove.

• Output: Confirmation signal indicating successful deletion.

• notion_retrieve_page

• Action: Gathers the structural and property data for a Notion page.

• Necessary Parameters:
  • page_id (string): Identifier of the target page.

• Output: Comprehensive page metadata.

• notion_update_page_properties

• Action: Modifies the metadata fields of an existing page.

• Necessary Parameters:
  • page_id (string): Identifier of the page to alter.
  • properties (object): A dictionary defining the property changes.

• Output: The updated page object.

• notion_create_database

• Action: Provisions a new database entity within the workspace.

• Necessary Parameters:
  • parent (object): Definition of the database's location.
  • properties (object): The schema defining the database columns/fields.
• Optional Parameters:
  • title (array): The display name for the new database (Rich Text format).

• Output: Details of the newly instantiated database.

• notion_query_database

• Action: Executes a structured query against a database's contents.

• Necessary Parameters:
  • database_id (string): Identifier of the database to search.
• Optional Parameters:
  • filter (object): Predicates used to narrow down results.
  • sorts (array): Specifications for ordering the output.
  • start_cursor (string): Token for pagination advancement.
  • page_size (number, default: 100, max: 100): Maximum number of results to return.

• Output: The filtered and sorted list of database entries.

• notion_retrieve_database

• Action: Retrieves the full definition and schema of a database.

• Necessary Parameters:
  • database_id (string): Identifier of the database.

• Output: Detailed database schema information.

• notion_update_database

  • Action: Modifies the high-level attributes or schema of a database.
  • Necessary Parameters:
  • database_id (string): Target database identifier.
  • Optional Parameters:
  • title (array): New textual designation.
  • description (array): Revised descriptive text.
  • properties (object): A revised set of column definitions.
  • Output: Information about the modified database record.

• notion_create_database_item

  • Action: Inserts a new record (page) into a specified database.
  • Necessary Parameters:
  • database_id (string): Target database identifier.
  • properties (object): Key-value pairs corresponding to the database's property schema.
  • Output: Metadata pertaining to the freshly created entry.

• notion_search

  • Action: Performs a global search across pages and databases based on title content.
  • Optional Parameters:
  • query (string): The string fragment to match within titles.
  • filter (object): Constraints to restrict results (e.g., only pages or only databases).
  • sort (object): Sorting criteria for the result set.
  • start_cursor (string): Pagination control token.
  • page_size (number, default: 100, max: 100): Maximum number of returned items.
  • Output: A collection of matching workspace objects.

• notion_list_all_users

  • Action: Retrieves a roster of every user account within the connected workspace.
  • Prerequisite Note: Successful execution often necessitates an Enterprise plan subscription and the use of an Organization-level API token.
  • Optional Parameters:
  • start_cursor (string): Token for paginating through extensive user lists.
  • page_size (number, max: 100): Limiter on the quantity of users returned per call.
  • Output: A paginated inventory of workspace members.

• notion_retrieve_user

  • Action: Fetches detailed records for an individual user via their ID.
  • Prerequisite Note: Requires Enterprise access/Organization token for broadest compatibility.
  • Necessary Parameters:
  • user_id (string): The unique identifier of the user.
  • Output: The profile data for the requested user.

• notion_retrieve_bot_user

  • Action: Retrieves the unique identity of the integration bot itself.
  • Output: Information identifying the bot user, including the authorizing user's details.

• notion_create_comment

  • Action: Posts a new textual annotation onto a page or discussion thread.
  • Constraint: Must specify EITHER a parent object (with page_id) OR a discussion_id, but not both.
  • Necessary Parameters:
  • rich_text (array): The content of the comment, structured as rich text objects.
  • Optional Parameters:
  • parent (object): Specifies the location, using page_id.
  • discussion_id (string): ID of an existing conversation to join.
  • Output: Confirmation and details of the newly lodged comment.

• notion_retrieve_comments

  • Action: Fetches a list of currently unresolved annotations tied to a page or block.
  • Prerequisite: Integration must possess the capability to read comments.
  • Necessary Parameters:
  • block_id (string): The identifier of the page or block from which to pull comments.
  • Optional Parameters:
  • start_cursor (string): Token for sequential result retrieval.
  • page_size (number, max: 100): Limit on the number of comments returned.
  • Output: A paginated roster of comments linked to the specified entity.

Licensing

This MCP server is distributed under the permissive MIT License. Users are granted extensive rights to utilize, modify, and redistribute this software, provided the original license terms are respected. Full details are available in the accompanying LICENSE file within the project's source repository.

WIKIPEDIA: Business management tools encompass the totality of systems, applications, controls, computational frameworks, and established methodologies employed by organizations to effectively navigate evolving market conditions, secure a durable competitive foothold, and systematically elevate overall operational performance.

== Conceptual Framework == Tools can be categorized based on the functional department they serve, and further classified by the aspect of management they address. Examples include instrumentation for strategic foresight, workflow management, record-keeping, personnel administration, judgment support, regulatory oversight, and more. A functional taxonomy generally recognizes:

• Instrumentation for data acquisition and integrity verification across all corporate sectors.
• Systems designed for the governance and refinement of organizational workflows.
• Platforms for aggregating information to support executive deliberation and decision-making. Today, the landscape of management instrumentation has been radically reshaped by rapid technological advancement, creating complexity in selecting optimal solutions for any given corporate need. This situation is driven by relentless pressure to lower expenditure while simultaneously maximizing revenue, the imperative to deeply understand customer requirements, and the need to deliver products precisely in the manner customers demand. Within this dynamic setting, leadership must adopt a strategic posture regarding management tooling, moving beyond mere adoption of the newest release. Frequently, managers implement tools without the necessary contextual modification, leading to operational instability. Therefore, business management instruments must be selected with great discernment and subsequently tailored to the organization's specific operational requirements, reversing the common practice.

== Prevalent Instruments == Data gathered by Bain & Company in 2013 illustrated global usage patterns of business instrumentation, reflecting how their outputs addressed regional priorities amid economic shifts. The leading ten tools identified were:

Strategic planning Customer relationship management Employee engagement surveys Benchmarking Balanced scorecard Core competency Outsourcing Change management programs Supply chain management Mission statement and vision statement Market segmentation Total quality management

== Commercial Software Applications == Software, defined as a suite of computer programs utilized by personnel to execute diverse corporate functions, is referred to as business software or an enterprise application. These applications serve to amplify productivity, quantify outcomes, and execute various organizational assignments with high precision. The evolution progressed from early Management Information Systems (MIS) to integrated Enterprise Resource Planning (ERP) systems. Subsequently, Customer Relationship Management (CRM) capabilities were incorporated, culminating in the current paradigm of cloud-based enterprise management suites. While a demonstrable link exists between IT investments and organizational success metrics, two factors are crucial for realizing maximum value: the efficacy of the implementation process and the rigorous methodology employed for selecting and adapting the appropriate technology.