notion-readonly

The Notion ReadOnly MCP Server provides a focused, read-only bridge to the Notion API, exposing a minimal set of tools optimized for AI assistants. It enables fast retrieval of pages, blocks, databases, comments, and page properties, with support for recursive page exploration and parallel content fetching. This design reduces tool surface area to improve performance and reliability when interacting with Notion content through an MCP-enabled client.

To use the server, configure it in your MCP client (for example Claude or another MCP-capable assistant) by pointing to the docker-based server and providing your Notion integration authorization header. The server exposes a small set of essential tools such as API-retrieve-a-page, API-get-block-children, API-retrieve-a-block, API-retrieve-a-database, API-retrieve-a-comment, API-retrieve-a-page-property, and API-get-one-pager. The API-get-one-pager tool recursively fetches a full page with blocks, databases, comments, and properties in a single call, leveraging parallel processing to speed up data retrieval. This makes it ideal for AI assistants that need quick, comprehensive context from Notion without a large toolset.

When using the docker deployment, ensure your OPENAPI_MCP_HEADERS includes your Bearer token and Notion-Version as shown in the examples. This server is designed for read-only access; ensure your integration token grants only the required Read Content permissions to minimize risk.

Prerequisites

• Docker installed on your machine
• Access to a Notion integration token with at least Read Content permissions

Step 1: Pull and run the MCP server via Docker

# Run the server (adjust token and version as needed)
docker run --rm -i \
  -e OPENAPI_MCP_HEADERS="{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2022-06-28\"}" \
  taewoong1378/notion-readonly-mcp-server

Step 2: Configure your MCP client

• In your MCP client configuration (e.g., Claude desktop config), add an entry under mcpServers using the docker command and the same image, providing the OPENAPI_MCP_HEADERS env var as shown in the Examples.

Example snippet for client config (as used in the README):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "OPENAPI_MCP_HEADERS",
        "taewoong1378/notion-readonly-mcp-server"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2022-06-28\"}"
      }
    }
  }
}

Step 3: Start using the MCP tools

• Once the container is running and the client is configured, you can call the available tools (e.g., API-retrieve-a-page, API-get-block-children, API-get-one-pager) to fetch content from Notion. For example, use API-get-one-pager to retrieve a full page with blocks, databases, and properties in a single call.

Security: Using a Notion integration with Read Content only minimizes risk, but exposing your integration token through tools like OPENAPI_MCP_HEADERS requires careful handling. Store tokens securely and limit the integration's capabilities to Read Content only. Performance: The server emphasizes parallel retrieval and caching for faster responses, especially for large Notion pages. If you encounter rate limits or slow responses, consider adjusting max depth for recursive fetches and enabling or inspecting the intelligent caching behavior. Environment variables to be aware of include OPENAPI_MCP_HEADERS (authorization header and Notion-Version). Ensure Notion-Version matches the API features you rely on. If you rotate tokens, update the OPENAPI_MCP_HEADERS value accordingly. Troubleshooting: If tools appear unavailable, verify the docker container is running, confirm the image tag taewoong1378/notion-readonly-mcp-server is accessible, and check that the host can reach Notion endpoints from the container. Logs from the container can help diagnose authentication or permission issues.