Notion + MCPHub (mcp.nvim): Complete MCP Integration

Notion is a MCP server that Notion's official hosted MCP server providing secure AI tool access to workspace content including pages, databases, and comments through OAuth authentication..

When integrated with MCPHub (mcp.nvim), you can:

• Search and retrieve live context from Notion workspace based on user access and permissions
• Access and query Notion databases to retrieve structured information
• Read page content and metadata from workspace pages you have access to

This guide provides step-by-step instructions to set up Notion in MCPHub (mcp.nvim), including configuration, examples, and troubleshooting.

What You'll Achieve

After completing this setup:

• Notion will be fully integrated and operational
• You can use Notion tools directly in MCPHub (mcp.nvim)
• All Notion capabilities will be available for your workflows
• Access to 4 different tools

Prerequisites

Before starting, ensure you have:

• Node.js 18 or higher (for STDIO transport only)
• Active Notion workspace with appropriate access permissions
• MCP client that supports remote servers (HTTP/SSE) or STDIO transport
• Notion account with workspace access
• Supported AI tool with MCP client capabilities
• Permission to connect external applications to workspace
• MCPHub (mcp.nvim) installed and configured
• Compatible operating system (Neovim 0.9+, Windows, macOS, Linux)

Installation

Step 1: Install Notion

Install using npm:

npx -y mcp-remote https://mcp.notion.com/mcp

Verify installation:

Connection verified through OAuth flow in your AI tool

Configuration

Step 2: Configure MCPHub (mcp.nvim)

1. Open MCPHub (mcp.nvim) settings
2. Navigate to MCP server configuration
3. Add Notion server with appropriate settings
4. Save and restart if needed

Examples

Once configured, you can use Notion in MCPHub (mcp.nvim):

Create Project Documentation

Generate PRDs, tech specs, or architecture docs by pulling context from existing Notion pages

Ask MCPHub (mcp.nvim): "Create a technical specification for the new authentication system based on our security guidelines in Notion"

Expected Result: AI retrieves security guidelines from Notion workspace and generates comprehensive tech spec

Track Campaign Progress

Monitor and report on campaign status using Notion database data

Ask MCPHub (mcp.nvim): "Give me a summary of all marketing campaigns in progress with their current metrics"

Expected Result: AI queries the campaigns database and provides formatted progress report

Search Meeting Notes

Find specific information across all meeting notes in workspace

Ask MCPHub (mcp.nvim): "What decisions did we make about the API redesign in recent meetings?"

Expected Result: AI searches meeting notes and returns relevant decisions with links to source pages

Generate Release Notes

Build release documentation by aggregating information from multiple Notion pages

Ask MCPHub (mcp.nvim): "Create release notes for version 2.0 using our changelog and feature pages"

Expected Result: AI compiles information from multiple pages into formatted release notes

Task Management

Query and analyze tasks from Notion databases

Ask MCPHub (mcp.nvim): "Show me all overdue tasks assigned to the engineering team"

Expected Result: AI filters and presents overdue engineering tasks with details and links

Testing Your Setup

1. Launch MCPHub (mcp.nvim)
2. Verify Notion is available in the tools list
3. Test basic Notion functionality

Troubleshooting

Common Issues

AI Tool Cannot Connect to Notion MCP

Symptoms: Connection timeout or failed errors, Notion MCP not appearing in tool directory, OAuth flow not starting

Cause: AI tool may not support MCP clients or remote MCP connections

Solution:

• Verify your AI tool supports MCP client functionality
• Check if tool supports remote MCP servers (HTTP/SSE transport)
• For tools without remote support, use STDIO with mcp-remote proxy: npx -y mcp-remote https://mcp.notion.com/mcp
• If tool lacks MCP support entirely, request feature from developers

OAuth Connection Fails

Symptoms: Authorization screen does not appear, Cannot complete OAuth flow, Connection succeeds but no workspace access

Cause: OAuth flow interrupted or workspace permissions issue

Solution:

• Use Notion app Settings > Connections > Notion MCP for easiest setup
• Ensure popup blockers are disabled during OAuth
• Check you have appropriate workspace permissions
• Try disconnecting and reconnecting through Notion app

Cannot Access Specific Pages or Databases

Symptoms: Some content returns not found errors, Searches return incomplete results, Database queries fail or return empty

Cause: Content access based on user permissions - AI tool can only see what you can see

Solution:

• Verify you have access to the pages/databases in Notion app
• Check workspace sharing settings for restricted content
• Ensure pages are not in private sections you cannot access
• Contact workspace admin if you need broader access

STDIO Transport Connection Issues

Symptoms: mcp-remote command fails, Connection drops frequently, Slow response times

Cause: STDIO transport requires mcp-remote proxy for hosted Notion MCP

Solution:

• Prefer Streamable HTTP or SSE transport if your tool supports it
• Ensure Node.js and npx are properly installed for STDIO
• Use config: npx -y mcp-remote https://mcp.notion.com/mcp
• Check network connectivity to mcp.notion.com

Tool Does Not Support Remote MCP Servers

Symptoms: Only local/STDIO servers work in tool, HTTP/SSE connections not available, No option to add remote server URL

Cause: Some MCP clients only support local STDIO servers

Solution:

• Use mcp-remote as proxy to convert HTTP to STDIO
• Configuration: command: npx, args: [-y, mcp-remote, https://mcp.notion.com/mcp]
• Alternative: Use open-source notion-mcp-server for local deployment
• Check tool documentation for remote server support roadmap

Plugin Not Loading or Command Not Found

Symptoms: :MCPHub command not recognized, Plugin not appearing in :PlugStatus, No errors but plugin inactive

Cause: Plugin not properly installed or configuration error

Solution:

• Verify plugin is added to plugin manager configuration
• Run plugin manager install command (:PackerInstall, :PlugInstall, or Lazy auto-install)
• Check for errors in :messages after sourcing config
• Ensure dependencies (plenary.nvim, nui.nvim) are installed
• Restart Neovim completely

MCP Server Won't Start

Symptoms: Server status shows "Error", Red indicator on server, Server immediately stops after starting

Cause: Invalid server configuration or missing dependencies

Solution:

• Verify npx is installed and in PATH: npx --version
• Check MCP server package exists: npx -y @modelcontextprotocol/server-filesystem --help
• Review server configuration in setup() - verify command and args
• Check server logs in MCPHub interface for detailed error messages
• Ensure required environment variables are set (e.g., GITHUB_TOKEN)
• Test server manually in terminal: npx -y @modelcontextprotocol/server-filesystem /path

UI Not Displaying Correctly

Symptoms: Blank window, Garbled text, Layout issues, Missing borders

Cause: Terminal or Neovim rendering issues

Solution:

• Verify Neovim version is 0.9 or higher: nvim --version
• Try different border style in ui.border config ("single", "double", "rounded")
• Check terminal supports Unicode and 256 colors
• Update nui.nvim dependency to latest version
• Test with different colorscheme to rule out theme conflicts

Integration with Avante/CodeCompanion Not Working

Symptoms: AI assistant not seeing MCP tools, Tool calls failing, Integration not recognized

Cause: Integration not enabled or incompatible versions

Solution:

• Verify integration is enabled in config: integrations.avante = true
• Ensure Avante.nvim/CodeCompanion.nvim is installed and loaded
• Check versions are compatible - update both plugins to latest
• Restart Neovim after enabling integration
• Check :checkhealth for integration-specific warnings

Marketplace Not Loading

Symptoms: :MCPHubMarketplace shows empty list, Network error in marketplace, Timeout loading servers

Cause: Network connectivity issues or marketplace service unavailable

Solution:

• Verify internet connectivity
• Check firewall allows HTTPS connections
• Try again later if marketplace service is temporarily down
• Review proxy settings if behind corporate firewall
• Check :messages for detailed network error messages

Project-Local Config Not Loading

Symptoms: .mcphub.json ignored, Project servers not appearing, Only global config loaded

Cause: Config file location or format issues

Solution:

• Verify .mcphub.json is in project root (same directory as .git)
• Check JSON syntax is valid using jsonlint or similar tool
• Ensure file name is exactly .mcphub.json (case-sensitive)
• Restart Neovim after creating/modifying project config
• Check file permissions are readable

Notion not appearing in MCPHub (mcp.nvim)

Symptoms: Server not listed, Tools not available

Cause: Configuration or installation issue

Solution:

• Verify configuration syntax
• Check Notion installation
• Restart MCPHub (mcp.nvim)
• Check logs for error messages

Next Steps

Now that Notion is integrated with MCPHub (mcp.nvim):

• Explore all Notion capabilities through MCPHub (mcp.nvim)
• Check out other MCP servers that work with MCPHub (mcp.nvim)
• Join the MCP community for tips and support
• Consider contributing to Notion development

Need Help?

• Search for Notion documentation
• Check the MCPHub (mcp.nvim) MCP guide
• Join the MCP community discussions