# awkoy/notion-mcp-server [Health: Active]

**Category:** 🛠️ Other Tools and Integrations  
**Repository:** https://github.com/awkoy/notion-mcp-server  
**GitHub Stars:** 179  
**npm Downloads (last month):** 7540  
**Views:** 8  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/awkoy-notion-mcp-server

## Description
Context-efficient alternative to the official Notion MCP: 43 operations (pages, databases, blocks, comments, files, templates) behind just 2 tools, 90% less context overhead. Token auth, so it runs headless in CI, cron, and background agents where OAuth-only can't.

## Tools
Capabilities this server exposes over MCP:

- **notion_read** — Run one Notion read operation by name. Nothing is modified.

Call: { operation, payload } — payload carries that operation's fields. Common: search_pages { query }, get_page { page_id }, get_page_markdown { page_id }, query_database { database_id, where? }, get_block_children { block_id }.

Responses are slimmed; pass verbose:true in payload for the raw Notion object. Every id field (page_id, block_id, database_id, view_id, …) also accepts a Notion URL, as copied from Share → Copy link. A block link's #fragment is used for block_id fields and a database link's ?v= for view_id fields.

If the payload is malformed, the error response includes the schema + a working example so you can correct and retry in one round-trip. Call notion_describe(operation) ahead of time only for complex shapes (query_database filters).
- **notion_write** — Run one Notion write operation by name. Archive, trash and delete operations remove content — confirm with the user before running them.

Two ways to call:
  • Single: { operation: "set_page_title", payload: { page_id, title } }
  • Batch:  { operation: "set_page_title", payload: { items: [{page_id, title}, ...], atomic?: false, idempotency_key?: "...", concurrency?: 3 } }
create_page, append_blocks, update_block and update_page_markdown also take a markdown string.

Responses are slimmed; pass verbose:true inside payload (single) or per item (batch) for the raw Notion object. Every id field (page_id, block_id, database_id, view_id, …) also accepts a Notion URL, as copied from Share → Copy link.

If the payload is malformed, the error response includes the schema + a working example so you can correct and retry in one round-trip. Call notion_describe(operation) ahead of time only for complex shapes (block trees, database property definitions, batch_mixed_blocks).
- **notion_describe** — Return the JSON Schema and a working example for one operation, plus which tool runs it (notion_read or notion_write). Use this BEFORE calling the operation when the payload shape is non-trivial (query filters, structured block trees, database property definitions). For simple ops, just call it — errors carry the schema.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "notion-mcp-server": {
    "command": "npx",
    "args": ["-y","notion-mcp-server"],
    "env": {
      "NOTION_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `NOTION_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What awkoy/notion-mcp-server does

awkoy/notion-mcp-server exposes Notion operations through three MCP tools rather than a separate tool for each API action. The read tool handles searches, page retrieval, database queries, block traversal, and other non-mutating operations. The write tool covers changes such as creating pages, editing titles and properties, appending or updating blocks, adding comments, uploading files, applying templates, and removing content. A third tool describes an operation's JSON Schema and supplies an example request.

The server supports 43 operations across pages, databases, blocks, comments, files, and templates. Page content can be read as markdown, and several write operations accept markdown for creating or revising page content. Responses are reduced by default to limit context usage; a `verbose` flag returns the underlying Notion object.

## How it works

Each read or write call includes an operation name and a payload containing that operation's fields. For example, a read request can use `search_pages` with a query, `get_page` with a page identifier, or `query_database` with a database identifier and optional filter. Write requests can be sent individually or as batches. Batch payloads can include multiple items, an atomic option, an idempotency key, and a concurrency limit.

Identifiers are flexible: fields such as page, block, database, and view IDs also accept copied Notion URLs. Block URL fragments can supply block identifiers, while the `v` query parameter in database links can supply view identifiers.

For complicated payloads—such as database filters, structured block trees, or database property definitions—`notion_describe` returns the expected schema and a usable example before execution. Simpler malformed requests return correction information with the error, allowing an agent to retry after one response.

## Setup and configuration

The server uses the `NOTION_TOKEN` environment variable. It accepts either a Notion Personal Access Token or an internal integration secret. A Personal Access Token follows the user's Notion access, while an internal integration is limited to pages explicitly connected to that integration.

The package can be added to MCP clients with `npx add-mcp notion-mcp-server --env NOTION_TOKEN=...`, or configured manually with an `mcpServers` entry that runs `npx -y notion-mcp-server`. The documented clients include Claude Desktop, Claude Code, Cursor, VS Code, Codex, Gemini CLI, Cline, Windsurf, Zed, and Continue. Docker can run the image `ghcr.io/awkoy/notion-mcp-server:latest` with standard input enabled for stdio transport.

Claude Code also has a plugin installation path that stores the token in the system keychain and requires Node.js 22 or later. The plugin can provide a default parent page and a read-only mode.

## Tools and capabilities

- `notion_read` runs named read operations without modifying Notion.
- `notion_write` runs named mutations, either singly or in batches.
- `notion_describe` returns operation schemas, examples, and the tool to use.
- Markdown input and output are available for supported page operations.
- Batch writes support atomic rollback, idempotency keys, and configurable concurrency.
- Slim responses reduce context use, with `verbose: true` available for raw objects.

## Limitations and notes

Archive, trash, and delete operations remove content and should be confirmed with the user before execution. Notion access depends on the permissions represented by the configured token; an internal integration must be connected to each page it needs to access. Keep `NOTION_TOKEN` in the client or process environment, and do not omit it from generated MCP configuration.

_Full upstream README: https://allmcps.com/mcp/awkoy-notion-mcp-server/readme_