{
  "markdown": "# better-mcp-notion\n\n[Japanese / 日本語](./README_ja.md)\n\n**An MCP server that lets you operate Notion with a single Markdown document.**\n\nExisting 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.\n\n## Why better-mcp-notion?\n\n| | Traditional Notion MCP | better-mcp-notion |\n|---|---|---|\n| Tools | 16-22 tools | **9 tools** |\n| Create a DB entry | 3+ calls (search DB, get schema, create page, append blocks) | **1 call** |\n| Edit a page | 4+ calls (get page, get blocks, delete blocks, append blocks) | **1 call** (read, edit, write) |\n| Format | Raw JSON blocks | **Markdown** |\n| Context window | Heavy (tool definitions + JSON) | **Light** |\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `read` | Read a Notion page as Markdown with frontmatter. Supports recursive child page reading with `depth`. |\n| `write` | Create or update pages from Markdown. Supports batch operations and append/prepend. |\n| `search` | Search the workspace by keyword. Returns a Markdown-formatted list. |\n| `list` | List database records as a table or child pages as a list. Supports natural language filter & sort. |\n| `update` | Quick property update without rewriting content. Just pass page + key-value pairs. |\n| `schema` | View or modify database schema — add, remove, or rename columns. |\n| `comment` | Add or read comments on a page. |\n| `delete` | Archive (soft-delete) a page. |\n| `move` | Move a page to a different parent page or database. |\n\n## Quick Start\n\n### 1. Create a Notion Integration\n\n1. Go to [notion.so/profile/integrations](https://www.notion.so/profile/integrations) and create a new integration\n2. Copy the API key (`ntn_...`)\n3. Share the pages/databases you want to access with the integration (\"Connect to\" in the page menu)\n\n### 2. Add to your MCP client\n\n#### Claude Code\n\n```bash\nclaude mcp add better-notion -- npx better-mcp-notion\n```\n\nThen set the environment variable:\n```bash\nexport NOTION_API_KEY=ntn_your_api_key_here\n```\n\n#### Claude Desktop / Cursor / Windsurf\n\nAdd to your MCP config file (e.g. `claude_desktop_config.json`, `.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"better-notion\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"better-mcp-notion\"],\n      \"env\": {\n        \"NOTION_API_KEY\": \"ntn_your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n#### From source\n\n```bash\ngit clone https://github.com/ai-aviate/better-mcp-notion.git\ncd better-mcp-notion\nnpm install && npm run build\n```\n\nThen point your MCP config to `node /path/to/better-mcp-notion/build/index.js`.\n\n## Usage\n\n### Read a page\n\n```\nread({ page: \"https://notion.so/My-Page-abc123def456\" })\n```\n\nReturns:\n\n```markdown\n---\nid: abc123-def456\ntitle: My Page\ndatabase: task-db-id\nproperties:\n  Status: In Progress\n  Tags:\n    - backend\n---\n## Notes\n- Completed API design\n```\n\n### Create a page\n\n```\nwrite({ markdown: `\n---\ntitle: Meeting Notes\nparent: \"Project Alpha\"\nicon: \"📝\"\n---\n## Agenda\n- Review progress\n- Discuss next steps\n` })\n```\n\n### Create a database entry\n\n```\nwrite({ markdown: `\n---\ntitle: Fix login bug\ndatabase: \"Task Board\"\nproperties:\n  Status: In Progress\n  Tags:\n    - backend\n    - urgent\n  Due Date: \"2026-03-01\"\n---\n## Description\nLogin fails when password contains special chars.\n` })\n```\n\n### Update a page (edit the output from read)\n\n```\nwrite({ markdown: `\n---\nid: abc123-def456\ntitle: Updated Title\nproperties:\n  Status: Done\n---\n## New content\nBody replaces all existing blocks.\n` })\n```\n\n### Append content to an existing page\n\nUse `position: \"append\"` to add content to the end without rewriting the entire page.\nOnly the new content needs to be provided — existing content is preserved.\n\n```\nwrite({ markdown: `\n---\nid: abc123-def456\n---\n## New section\nThis is added to the end of the page.\n`, position: \"append\" })\n```\n\n`position: \"prepend\"` adds content to the beginning instead.\n\n### Batch create (multiple pages in one call)\n\nSeparate pages with `===`:\n\n```\nwrite({ markdown: `\n---\ntitle: Task 1\ndatabase: \"Task Board\"\nproperties:\n  Status: Todo\n---\nTask 1 details\n===\n---\ntitle: Task 2\ndatabase: \"Task Board\"\nproperties:\n  Status: Todo\n---\nTask 2 details\n` })\n```\n\n### Query a database with filters\n\n```\nlist({\n  target: \"Task Board\",\n  filter: \"Status is Done AND Priority is High\",\n  sort: \"Due Date ascending\"\n})\n```\n\n#### Filter syntax\n\n- `Status is Done` / `Status = Done` - equals\n- `Priority != Low` - not equals\n- `Tags contains backend` - multi-select contains\n- `Done is true` - checkbox\n- `Score > 80` - number comparison (`>`, `<`, `>=`, `<=`)\n- `Due Date after 2026-03-01` - date after/before\n- Combine with `AND`: `Status is Done AND Priority is High`\n\n#### Sort syntax\n\n- `Due Date ascending` or `Due Date asc`\n- `Created descending` or `Created desc`\n\n### Read with child pages\n\n```\nread({ page: \"parent-page-id\", depth: 2 })\n```\n\n`depth: 1` = current page only (default), `2` = include children, `3` = include grandchildren.\n\n### Quick property update\n\nUpdate properties without rewriting content:\n\n```\nupdate({ page: \"My Task\", properties: { \"Status\": \"Done\", \"Priority\": \"High\" } })\n```\n\n### Manage database schema\n\n```\n// View schema\nschema({ database: \"Task Board\" })\n\n// Add a column\nschema({ database: \"Task Board\", action: \"add\", property: \"Priority\", type: \"select\", options: [\"Low\", \"Medium\", \"High\"] })\n\n// Rename a column\nschema({ database: \"Task Board\", action: \"rename\", property: \"Due\", name: \"Due Date\" })\n\n// Remove a column\nschema({ database: \"Task Board\", action: \"remove\", property: \"Old Column\" })\n```\n\n### Comments\n\n```\n// Read comments\ncomment({ page: \"abc123\" })\n\n// Add a comment\ncomment({ page: \"abc123\", body: \"Looks good! Ready to ship.\" })\n```\n\n## Frontmatter Reference\n\n### Write (create/update)\n\n| Field | Create | Update | Description |\n|-------|--------|--------|-------------|\n| `id` | - | **required** | Page ID to update |\n| `title` | recommended | optional | Page title |\n| `parent` | required* | ignored | Parent page name or ID |\n| `database` | required* | ignored | Database name or ID (*either `parent` or `database`) |\n| `icon` | optional | optional | Emoji or image URL |\n| `cover` | optional | optional | Cover image URL |\n| `properties` | optional | optional | Database properties (matched against schema) |\n\n### Read (output only)\n\n| Field | Description |\n|-------|-------------|\n| `id` | Page UUID |\n| `url` | Notion page URL |\n| `title` | Page title |\n| `parent` / `database` | Parent page or database ID |\n| `icon`, `cover` | Emoji or image URL |\n| `properties` | All database properties |\n| `created`, `last_edited` | Timestamps (read-only) |\n\nRead-only fields (`url`, `created`, `last_edited`, formulas, etc.) are safely ignored when passed to `write`.\n\n## Development\n\n```bash\nnpm run dev          # TypeScript watch mode\nnpm test             # Run tests\nnpm run test:watch   # Test watch mode\n```\n\n## License\n\n[Elastic License 2.0 (ELv2)](./LICENSE) — Free to use, modify, and distribute. Cannot be offered as a managed/hosted service.\n",
  "bytes": 7128,
  "sha": "29c8a1381d88ee6666ce95ab7f2a51f9b03dca58e9dc9a58e4a9784a8b6c94c4",
  "repo_slug": "ai-aviate/better-mcp-notion",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ai_aviate_better_notion_2ee8c4aa/readme"
}