mcp-notion

This MCP server exposes a Notion-based note navigation experience. It indexes Notion pages starting from a ROOT_PAGE and exposes notes as text/markdown resources with UUID slugs, enabling you to browse, search, and retrieve related pages via MCP-compatible tools. The server provides a resource interface to list and fetch notes (note:// URIs), a search_notes tool to locate relevant Notion pages using a query string, and a set of prompts to summarize, refactor, fix, or enhance individual notes. The design focuses on graph-aware retrieval, considering parent-child and reference relationships to surface contextually relevant Notion content.

To use it, configure ROOT_PAGE with your Notion root page ID, then run the server. Client tools and prompts can query the server for markdown content and metadata, enabling workflows that read and summarize Notion pages, propose structural improvements, or generate enhancements to notes. The MCP setup makes it possible to integrate Notion pages into broader AI-assisted workflows by exposing them through standard MCP channels (resources, tools, prompts).

Prerequisites:

• Node.js and npm/yarn/pnpm installed on your system
• Git to clone the repository (if needed)

Install and build (example workflow):

1. Clone the repository: git clone https://github.com/your-org/mcp-notion.git cd mcp-notion

2. Install dependencies using pnpm (as recommended by the project): pnpm install

3. Build the project: pnpm build

4. Run in development or production mode (adjust paths as needed):

   • Development with auto-rebuild: pnpm watch
   • Start the server manually (after build): node /path/to/mcp/build/index.js

5. Optional: configure MCP Inspector for debugging: pnpm inspector

Environment configuration:

• Set ROOT_PAGE to the Notion root page ID you want to start from. This is required for the Notion-based navigation.
• Any additional environment variables required by the server can be added to the mcp config or environment as needed.

Tips and troubleshooting:

• Ensure ROOT_PAGE is the proper Notion page ID and that your Notion workspace permissions allow access.
• If you encounter issues with Notion API access, verify network connectivity and any required API keys or tokens per your Notion integration setup.
• When using Claude Desktop integration, ensure the mcpServers configuration in Claude's config points to the correct node/index.js path and that ROOT_PAGE is provided.
• The server uses SSEServerTransport for remote communication; ensure network endpoints and ports are correctly configured for remote deployment.
• If you modify prompts or add new tools, rebuild the project to pick up changes.
• For debugging, use the MCP Inspector with pnpm inspector to inspect stdio-based server communication and tool invocations.