The Notion MCP server, its live tool list captured on a real Mac.

• Tools

  24, enumerated live

• Credentials

  Notion integration secret [5]

• Transport

  stdio, runs on your Mac [5]

• Maintainer

  Notion Labs (makenotion) [1][3]

• Downloads

  209k last week [2]

• License

  MIT [4]

Verification

How this MCP server was verified.

Method

We spawned the server with npx over stdio with no environment variables set at all: no NOTION_TOKEN, no OPENAPI_MCP_HEADERS. It started anyway, completed the MCP initialize handshake, and answered tools/list with 24 tools. The tool table below is that capture, word for word. We then ran one read-only call, API-post-search, and the server passed it to Notion and returned the real reply: a 401 saying the API token is invalid, which is printed below exactly as it came back. A tool call that actually reaches a workspace is still pending credentials, so this page carries the enumerated badge and not the verified one. The server prints nothing to stderr on startup, so the banner below is the raw initialize response it wrote on the wire.

{"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"Notion API","version":"1.0.0"}},"jsonrpc":"2.0","id":1}

tools/call API-post-search {"query": "Getting started", "page_size": 1}

{"status":401,"object":"error","code":"unauthorized","message":"API token is invalid.","request_id":"ede4937b-fa79-4222-8515-b404299d6f82"}

Real lines from the captured result: enough to prove the call answered.

Tools

Every tool, enumerated from the running server.

The server answered tools/list with 24 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.

Parameters marked with * are required.

Setup

Working configs, one per app.

Copy the block for the app you use. Each one is the configuration this server was verified with.

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_your_integration_secret"
      }
    }
  }
}

claude mcp add --env NOTION_TOKEN=ntn_your_integration_secret --transport stdio notion -- npx -y @notionhq/notion-mcp-server

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_your_integration_secret"
      }
    }
  }
}

Name                   Notion
Command                npx
Arguments              -y @notionhq/notion-mcp-server
Environment Variables  NOTION_TOKEN = ntn_your_integration_secret

No terminal needed

Set the Notion MCP server up without the terminal.

If you have never opened Terminal and never want to, this is your path. Routines is a Mac app that runs MCP servers for you: fill in four fields once, and this server's tools are available to your AI in chat and in scheduled routines. The only preparation happens inside Notion, and it takes about two minutes.

1. 01

   Create the integration in Notion

   Go to notion.so/profile/integrations and create a new internal integration. Copy the secret it shows you: it starts with ntn_. On the Configuration tab you can tick Read content only, which gives you a token that can look but never write.

2. 02

   Share the pages you want it to see

   An integration starts with access to nothing. In the integration settings, open the Access tab and pick the pages and databases it may use. Anything you do not share stays invisible to the server.

3. 03

   Install Routines and open the MCP settings

   Download the app from getroutines.ai/download, drag it to Applications, and sign in. Click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.

4. 04

   Choose Command (stdio)

   The form opens in URL (SSE/HTTP) mode. Switch it to Command (stdio): this server is a command, not a web address. Name: Notion. Command: npx. Arguments: -y @notionhq/notion-mcp-server, with nothing after it.

5. 05

   Paste the secret as an environment variable

   In Environment Variables add one entry, NOTION_TOKEN, with the ntn_ secret as its value. Do not put it in Arguments: that field splits on spaces and is not the place for a credential.

6. 06

   Test, add, then use it

   Click Test Connection: Routines starts the server and reports how many tools it found, twenty-four for this one. Then click Add Server. The tools work in chat right away. To let a scheduled routine use them, open the routine, find the Tools & connections card, and tick the server under Apps.

Routine ideas

Routines worth scheduling.

Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.

Troubleshooting

The errors we hit, and what fixed them.

Real errors captured during the verification run, printed exactly as the server returned them.

{"status":401,"object":"error","code":"unauthorized","message":"API token is invalid.","request_id":"ede4937b-fa79-4222-8515-b404299d6f82"}

Failed to parse OPENAPI_MCP_HEADERS environment variable: SyntaxError: Expected property name or '}' in JSON at position 1 (line 1 column 2)

{"error":"invalid_token","error_description":"Missing or invalid access token"}

FAQ

Questions people ask.

Sources

Every external claim, receipted.

Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.

1. [1]

   npm registry: @notionhq/notion-mcp-serveraccessed 2026-08-03

   Latest version 2.5.1, published 2026-07-25; described as the official MCP server for the Notion API; every publishing maintainer is a Notion address.

2. [2]

   npm downloads API: last weekaccessed 2026-08-03

   209,337 downloads for the week ending 2026-08-01.

3. [3]

   GitHub: makenotion/notion-mcp-serveraccessed 2026-08-03

   4,566 stars and a push dated 2026-07-25 at access time, per the GitHub API; owned by the makenotion organisation.

4. [4]

   makenotion/notion-mcp-server LICENSE fileaccessed 2026-08-03

   We read the file: it is the MIT License text, copyright 2025 Notion Labs, Inc.

5. [5]

   Notion MCP Server READMEaccessed 2026-08-03

   The NOTION_TOKEN and OPENAPI_MCP_HEADERS contract, stdio as the default transport, the integration and Access tab steps, and the 22-tool figure from the 2.0.0 notes.

6. [6]

   Notion developers: Connecting to Notion MCPaccessed 2026-08-03

   The hosted server at https://mcp.notion.com/mcp, its OAuth flow, per-client config, and the note that the open-source server is no longer actively maintained.

7. [7]

   modelcontextprotocol.io: Connect to local MCP serversaccessed 2026-08-03

   The claude_desktop_config.json location and shape for a local stdio server.

8. [8]

   Claude Code docs: MCPaccessed 2026-08-03

   The claude mcp add syntax for stdio servers with --env, and for remote servers with --transport http.

9. [9]

   Cursor docs: Model Context Protocolaccessed 2026-08-03

   The mcp.json shape and file locations.

10. [10]

    Routines: Connectorsaccessed 2026-08-03

    How Routines runs one-click OAuth connectors and any MCP server.

This page describes Notion as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.