aalhommada/nextjs-docs-mcp

Next.js Documentation MCP Server

A Model Context Protocol (MCP) server for accessing and searching Next.js documentation. This package provides programmatic access to Next.js documentation through a simple interface.

Features

• 🔍 Search Documentation: Search through Next.js documentation with natural language queries
• 📖 Full Page Access: Retrieve complete documentation pages by URL
• 💡 Best Practices: Get curated best practices for specific Next.js topics
• 📊 Cache Statistics: Monitor cache performance and statistics
• 🔄 Smart Caching: Documentation is cached with size limits and expiration (6 hours)
• ⚡ Performance Optimized: Concurrent scraping and efficient search algorithms
• 🔒 Security Enhanced: Rate limiting (30 requests/minute) to prevent abuse
• 🌐 Comprehensive Coverage: Covers all major Next.js documentation sections including:
  • Getting Started
  • App Router
  • Pages Router
  • API Reference
  • Functions
  • Optimization
  • Security
  • Advanced Topics

Quick Installation

Choose your platform:

Claude Code Terminal (Windows):

Due to a Windows-specific issue with the claude mcp add command, use this automated installer:

npx @aalhommada/nextjs-docs-mcp install-claude

Or manually run this PowerShell command:

powershell -ExecutionPolicy Bypass -Command "$config = Get-Content '$env:USERPROFILE\.claude.json' | ConvertFrom-Json; $projectPath = (Get-Location).Path; if (-not $config.projects.$projectPath) { $config.projects | Add-Member -NotePropertyName $projectPath -NotePropertyValue @{allowedTools=@(); history=@(); mcpContextUris=@(); mcpServers=@{}; enabledMcpjsonServers=@(); disabledMcpjsonServers=@(); hasTrustDialogAccepted=$false} }; $config.projects.$projectPath.mcpServers.'nextjs-docs' = @{type='stdio'; command='cmd'; args=@('/c', 'npx', '-y', '@aalhommada/nextjs-docs-mcp'); env=@{}}; $config | ConvertTo-Json -Depth 100 | Set-Content '$env:USERPROFILE\.claude.json'; Write-Host 'MCP installed! Run: claude mcp list'"

Claude Code Terminal (Mac/Linux):

claude mcp add --transport stdio nextjs-docs -- npx -y @aalhommada/nextjs-docs-mcp

VS Code (Cline): Add to settings.json:

{
  "mcp.servers": {
    "nextjs-docs": {
      "command": "npx",
      "args": ["-y", "@aalhommada/nextjs-docs-mcp"]
    }
  }
}

Cursor: Add to MCP Settings:

{
  "mcpServers": {
    "nextjs-docs": {
      "command": "npx",
      "args": ["-y", "@aalhommada/nextjs-docs-mcp"]
    }
  }
}

Requirements

• Node.js >= 20.0

Usage

This package provides an MCP server that can be used with tools like Claude or other AI assistants that support the Model Context Protocol.

Available Tools

1. search_nextjs_docs

   • Search the Next.js documentation for relevant information
   • Input: query (string)

2. get_nextjs_page

   • Get the full content of a specific Next.js documentation page
   • Input: url (string)

3. get_nextjs_best_practices

   • Get current Next.js best practices for a specific topic
   • Input: topic (string)

4. get_nextjs_cache_stats

   • Get statistics about the documentation cache
   • Input: none

Using with Claude Code Terminal

Windows:

npx @aalhommada/nextjs-docs-mcp install-claude

Mac/Linux:

claude mcp add --transport stdio nextjs-docs -- npx -y @aalhommada/nextjs-docs-mcp

Verify it's working:

claude mcp list

Now you can ask Claude questions about Next.js documentation in any conversation:

• "How do I implement server-side rendering in Next.js?"
• "Show me the best practices for data fetching"
• "What are the latest features in App Router?"

Using with VS Code (Cline Extension)

1. Install the Cline extension from VS Code marketplace

2. Open VS Code Settings (JSON) by pressing Ctrl+Shift+P (or Cmd+Shift+P on Mac) and search for "Preferences: Open User Settings (JSON)"

3. Add this MCP server configuration to your settings:

{
  "mcp.servers": {
    "nextjs-docs": {
      "command": "npx",
      "args": ["-y", "@aalhommada/nextjs-docs-mcp"],
      "transport": "stdio"
    }
  }
}

4. Restart VS Code and the MCP server will automatically connect when you use Cline

Now you can ask Next.js documentation questions directly in the Cline chat!

Using with Cursor

1. Open Cursor Settings: Cursor > Settings > Cursor Settings (or press Ctrl+Shift+J / Cmd+Shift+J)

2. Click on "Models" tab, scroll down to find "MCP Settings"

3. Add this configuration to your MCP settings:

{
  "mcpServers": {
    "nextjs-docs": {
      "command": "npx",
      "args": ["-y", "@aalhommada/nextjs-docs-mcp"]
    }
  }
}

4. Restart Cursor and the MCP server will automatically connect

Now you can ask questions in Cursor's chat:

• "How do I set up middleware in Next.js 14?"
• "Show me examples of API routes"
• "What are the best practices for image optimization?"

Quick Start (npx)

You can also run the MCP server directly without installation:

npx @aalhommada/nextjs-docs-mcp

This is useful for testing or one-time usage.

Development

1. Clone the repository:

   git clone https://github.com/aalhommada/nextjs-docs-mcp.git
   cd nextjs-docs-mcp
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Start the server:

   npm start
   

Performance & Security Features

Caching Strategy

• Documentation is cached for 6 hours with automatic refresh
• Maximum cache size of 500 pages
• Content truncation for large pages (100KB limit)
• Graceful degradation when scraping fails

Rate Limiting

• 30 requests per minute per client
• Automatic reset of counters
• Clear error messages when limits are exceeded

Error Handling

• Comprehensive error handling for network issues
• Fallback to stale cache when scraping fails
• Detailed logging for debugging

Technical Details

• Built with TypeScript for type safety
• Uses cheerio for HTML parsing
• Implements efficient caching mechanism
• Follows MCP server specifications
• Secure by design with rate limiting

License

MIT

Author

Abdullah Al Hommada

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.