Introduction

When reading or writing Notion in the dsh agent, common problems are not just about whether tools can be invoked, but also include OAuth authorization, token refresh, local callbacks, credential storage, and invalidation handling.

dsh-notion-mcp is a DeepSeek Harness (DSH) plugin that connects dsh to Notion via the official Notion MCP server using OAuth 2.0 (Authorization Code + PKCE). After completing the one-time browser authorization, Notion tools such as search, pages, databases, and comments will be mounted to the dsh agent in the form of mcp__notion__*.

Below is an introduction to its positioning, features, installation methods, authorization flow, and notes.

What is this

dsh-notion-mcp is a DSH plugin used to connect dsh to Notion.

It uses the official Notion MCP server and completes browser authorization via OAuth 2.0 (Authorization Code + PKCE). The plugin is responsible for handling client registration, token exchange, token refresh, and credential storage, ultimately allowing the dsh agent to directly invoke mcp__notion__* tools.

The license is MIT. The GitHub repository is located at:

https://github.com/mingzeng21/dsh-notion

Core Features

dsh-notion-mcp provides the following verified capabilities:

  • Connects dsh to Notion via the official Notion MCP server.
  • Completes one-time browser authorization using OAuth 2.0 (Authorization Code + PKCE).
  • Runtime dynamic client registration (RFC 7591), without needing to provide client_id or secrets.
  • Automatically refreshes access tokens before they expire, with atomic persistence of refresh tokens.
  • Mounts Notion tools like search, pages, databases, and comments to the dsh agent as mcp__notion__*.
  • Tokens are stored in the DSH credentials layer, not in the repository.
  • Clears and stops retrying when the refresh token encounters invalid_grant.

Environment Requirements

Before running, ensure the DSH and Node.js versions are confirmed:

  • DeepSeek Harness (dsh) has been verified to be compatible with the following versions:
  • v0.1.0-rc.8
  • v0.1.1-rc.1
  • v0.1.1-rc.2
  • v0.1.2-alpha.1
  • Node.js requirements: ^22.19.0 or >=24.0.0.
  • Node 23 is out of scope.

Installation

The installation command is as follows:

dsh plugin --profile web add dsh-notion-mcp

The --profile in the installation command is used to specify the profile for the plugin. If you want to run the notion command in the minimal profile, you can also install it in that profile:

dsh plugin --profile notion add dsh-notion-mcp

Note: The notion command needs to be run in the minimal profile; UI apps like web do not forward notion to the plugin.

Authorization

Authorization is performed in the minimal profile. Below is an example using the notion profile:

dsh --profile notion notion login

After execution, dsh notion login will print the authorization URL and wait for a callback at 127.0.0.1:53007.

Open the printed authorization URL in a browser. After approval, Notion will redirect to:

http://127.0.0.1:53007/callback

After authorization is complete, Notion tools will be available in the form of mcp__notion__*.

The local OAuth callback port is 53007 and the listening address is 127.0.0.1.

Configuration

The default configuration items are as follows:

mcpUrl: https://mcp.notion.com/mcp

mcpUrl is the URL of the Notion MCP server.

Security and Notes

It is recommended to check the repository source code and license before use. The plugin runs with the permissions of the current dsh process; ensure you trust the repository, dependencies, and your running environment before installing.

Verified security-related behaviors include:

  • Tokens are stored in the DSH credentials layer, not in the repository.
  • The repository does not contain any secrets.
  • Runtime dynamic client registration, without needing to provide client_id or secrets.
  • Atomic persistence of refresh tokens.
  • Notion rotates the refresh token on every refresh.
  • If the refresh token encounters invalid_grant, the plugin will clear it and stop retrying; you need to re-run:
dsh notion login

Uninstallation

The uninstallation command is as follows:

dsh plugin --profile web remove dsh-notion-mcp

Repository

The GitHub repository is located at:

https://github.com/mingzeng21/dsh-notion

License: MIT.