Related Pages

Related topics: Entrypoints and Runtime Surface, Architecture Evidence Map, Operations and Verification Boundaries

Repository Overview

This page is generated from repository evidence because the Human Wiki provider was unavailable. It intentionally limits itself to README and file-tree facts.

README Evidence

better-mcp-notion

Japanese / 日本語

An MCP server that lets you operate Notion with a single Markdown document.

Existing Notion MCP servers are thin API wrappers that require multiple round-trips for a single operation. better-mcp-notion uses one Markdown document (YAML frontmatter + body) to read, create, and update pages in a single call.

Why better-mcp-notion?

Tools

Quick Start

1. Create a Notion Integration

1. Go to notion.so/profile/integrations and create a new integration
2. Copy the API key (ntn_...)
3. Share the pages/databases you want to access with the integration ("Connect to" in the page menu)

2. Add to your MCP client

#### Claude Code

claude mcp add better-notion -- npx better-mcp-notion

Then set the environment variable:

export NOTION_API_KEY=ntn_your_api_key_here

#### Claude Desktop / Cursor / Windsurf

Add to your MCP config file (e.g. claude_desktop_config.json, .cursor/mcp.json):

{
  "mcpServers": {
    "better-notion": {
      "command": "npx",
      "args": ["-y", "better-mcp-notion"],
      "env": {
        "

[excerpt truncated]

## Selected Source Inventory

- `README.md`
- `package.json`
- `src/errors.ts`
- `src/index.ts`
- `src/server.ts`
- `src/converter/frontmatter.ts`
- `src/converter/to-markdown.ts`
- `src/converter/to-notion.ts`
- `src/converter/types.ts`
- `src/notion/client.ts`
- `src/notion/helpers.ts`
- `src/tools/comment.ts`

| File | Evidence role | Size |
|---|---|---|
| `README.md` | README/product and usage evidence | 7142 bytes |
| `package.json` | package/runtime metadata | 1357 bytes |
| `src/errors.ts` | implementation surface | 1907 bytes |
| `src/index.ts` | implementation surface | 379 bytes |
| `src/server.ts` | implementation surface | 983 bytes |
| `src/converter/frontmatter.ts` | implementation surface | 9313 bytes |
| `src/converter/to-markdown.ts` | implementation surface | 1818 bytes |
| `src/converter/to-notion.ts` | implementation surface | 1095 bytes |
| `src/converter/types.ts` | implementation surface | 1611 bytes |
| `src/notion/client.ts` | implementation surface | 14345 bytes |
| `src/notion/helpers.ts` | implementation surface | 1711 bytes |
| `src/tools/comment.ts` | implementation surface | 3181 bytes |

Source: `[README.md:1-120]()`

Related Pages

Related topics: Repository Overview, Architecture Evidence Map, Operations and Verification Boundaries

Entrypoints and Runtime Surface

The files below are the highest-signal candidates for how the project is installed, started, configured, or embedded. Treat this as an evidence map, not an inferred API contract.

Source: README.md:1-120

Related Pages

Related topics: Repository Overview, Entrypoints and Runtime Surface, Operations and Verification Boundaries

Architecture Evidence Map

This section maps source paths into likely architectural areas based on repository layout only. Claims that require execution are intentionally not made here.

• .: README.md, package.json
• src: src/errors.ts, src/index.ts, src/server.ts, src/converter/frontmatter.ts, src/converter/to-markdown.ts, src/converter/to-notion.ts

Source: package.json:1-120

Related Pages

Related topics: Repository Overview, Entrypoints and Runtime Surface, Architecture Evidence Map

Operations and Verification Boundaries

Operational guidance is limited to files that are present in the repository. Before using this project in an agent workflow, verify install, quickstart, and runtime behavior in a sandbox.

• Documentation signal: README.md
• Runtime/package signal: package.json
• Source inspection signal: src/errors.ts
• Source inspection signal: src/index.ts
• Source inspection signal: src/server.ts
• Source inspection signal: src/converter/frontmatter.ts
• Source inspection signal: src/converter/to-markdown.ts
• Source inspection signal: src/converter/to-notion.ts
• Source inspection signal: src/converter/types.ts
• Source inspection signal: src/notion/client.ts

Source: src/errors.ts:1-120

Doramagic Pitfall Log

Doramagic extracted 6 source-linked risk signals. Review them before installing or handing real data to the project.

1. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | mcp_registry:io.github.ai-aviate/better-notion:0.3.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ai-aviate%2Fbetter-notion/versions/0.3.2 | README/documentation is current enough for a first validation pass.

2. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.ai-aviate/better-notion:0.3.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ai-aviate%2Fbetter-notion/versions/0.3.2 | last_activity_observed missing

3. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | mcp_registry:io.github.ai-aviate/better-notion:0.3.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ai-aviate%2Fbetter-notion/versions/0.3.2 | no_demo; severity=medium

4. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | mcp_registry:io.github.ai-aviate/better-notion:0.3.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ai-aviate%2Fbetter-notion/versions/0.3.2 | no_demo; severity=medium

5. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.ai-aviate/better-notion:0.3.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ai-aviate%2Fbetter-notion/versions/0.3.2 | issue_or_pr_quality=unknown

6. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.ai-aviate/better-notion:0.3.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ai-aviate%2Fbetter-notion/versions/0.3.2 | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using better-mcp-notion with real data or production workflows.

• README/documentation is current enough for a first validation pass. - GitHub / issue