Troubleshooting

This guide helps you resolve common issues when setting up or using Context7 MCP.

Quick Checklist#

• Confirm Node.js v20+ is installed (node --version)
• Update to the latest Context7 MCP package (@upstash/context7-mcp@latest)
• Verify connectivity with curl https://mcp.context7.com/ping
• Add your API key to the configuration if you hit rate limits
• Enable debug logs (DEBUG=*) before collecting support information

Common Fixes#

Use Latest Version#

Add @latest to ensure you're using the most recent version:

{  "mcpServers": {    "context7": {      "command": "npx",      "args": ["-y", "@upstash/context7-mcp@latest", "--api-key", "YOUR_API_KEY"]    }  }}

Module Not Found / Use Alternative Runtimes#

If you encounter ERR_MODULE_NOT_FOUND, try bunx or deno instead of npx:

{  "mcpServers": {    "context7": {      "command": "bunx",      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]    }  }}

{  "mcpServers": {    "context7": {      "command": "deno",      "args": ["run", "--allow-env=NO_DEPRECATION,TRACE_DEPRECATION", "--allow-net", "npm:@upstash/context7-mcp"]    }  }}

ESM Resolution Issues#

For Error: Cannot find module 'uriTemplate.js', use the --experimental-vm-modules flag:

{  "mcpServers": {    "context7": {      "command": "npx",      "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"]    }  }}

TLS/Certificate Issues#

Use the --experimental-fetch flag:

{  "mcpServers": {    "context7": {      "command": "npx",      "args": ["-y", "--node-options=--experimental-fetch", "@upstash/context7-mcp"]    }  }}

Node.js Version#

Ensure you're using Node.js v20 or higher (node --version).

Platform-Specific Issues#

Windows Issues#

Request Timeout Errors#

On Windows, some users may encounter request timeout errors with the default configuration. Try using the full path to Node.js and the installed package:

{  "mcpServers": {    "context7": {      "command": "C:\\Program Files\\nodejs\\node.exe",      "args": [        "C:\\Users\\yourname\\AppData\\Roaming\\npm\\node_modules\\@upstash\\context7-mcp\\dist\\index.js",        "--transport",        "stdio",        "--api-key",        "YOUR_API_KEY"      ]    }  }}

Alternatively, use this configuration with cmd:

{  "mcpServers": {    "context7": {      "command": "cmd",      "args": ["/c", "npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]    }  }}

macOS Issues#

Request Timeout Errors#

On macOS, some users may encounter the same request timeout errors. Use the full path to Node.js and the installed package:

{  "mcpServers": {    "context7": {      "command": "/Users/yourname/.nvm/versions/node/v22.14.0/bin/node",      "args": [        "/Users/yourname/.nvm/versions/node/v22.14.0/lib/node_modules/@upstash/context7-mcp/dist/index.js",        "--transport",        "stdio",        "--api-key",        "YOUR_API_KEY"      ]    }  }}

API and Connection Issues#

Rate Limiting#

If you encounter rate limit errors:

• Get an API key: Sign up at context7.com/dashboard for higher rate limits
• Add the API key to your configuration:

{  "mcpServers": {    "context7": {      "url": "https://mcp.context7.com/mcp",      "headers": {        "Authorization": "Bearer YOUR_API_KEY"      }    }  }}

Authentication Errors#

If you see 401 Unauthorized errors:

1. Verify your API key is correct and starts with ctx7sk
2. Check the header format - ensure the API key is properly set:

For HTTP transport:

{  "headers": {    "Authorization": "Bearer YOUR_API_KEY"  }}

For stdio transport:

{  "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]}

Library Not Found#

If you get 404 Not Found errors:

1. Verify the library ID format is correct: /owner/repo or /owner/repo/version
2. Search for the library first using resolve-library-id tool
3. Check if the library exists at context7.com

MCP Client-Specific Issues#

Cursor#

• Make sure you're using Cursor 1.0 or later for the best MCP support
• Try both global (~/.cursor/mcp.json) and project-specific (.cursor/mcp.json) configurations
• Restart Cursor after changing the MCP configuration

VS Code#

• Ensure you have the latest version of VS Code with MCP support
• Check that the Copilot extension is installed and updated
• Restart VS Code after configuration changes

Claude Code#

• Verify the MCP server is added correctly with claude mcp list
• Check logs with claude mcp logs context7
• Try removing and re-adding the server

Configure HTTPS Proxy#

If you're behind a corporate proxy, configure Context7 to route through it.

Set Environment Variables#

export https_proxy=http://proxy.example.com:8080export HTTPS_PROXY=http://proxy.example.com:8080

export https_proxy=http://username:password@proxy.example.com:8080

set https_proxy=http://proxy.example.com:8080set HTTPS_PROXY=http://proxy.example.com:8080

set https_proxy=http://username:password@proxy.example.com:8080

$env:https_proxy = "http://proxy.example.com:8080"$env:HTTPS_PROXY = "http://proxy.example.com:8080"

Or Configure in MCP Settings#

Add proxy directly to your MCP configuration:

{  "mcpServers": {    "context7": {      "command": "npx",      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"],      "env": {        "https_proxy": "http://proxy.example.com:8080",        "HTTPS_PROXY": "http://proxy.example.com:8080"      }    }  }}

Both lowercase and uppercase environment variables are supported.

Debugging Tips#

Enable Verbose Logging#

Add debug output to your configuration:

{  "mcpServers": {    "context7": {      "command": "npx",      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"],      "env": {        "DEBUG": "*"      }    }  }}

Test with MCP Inspector#

Test your setup independently:

npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp

This opens an interactive inspector to test Context7 tools.

Check Server Status#

Test that the remote server is reachable:

curl https://mcp.context7.com/ping

Expected response: {"status": "ok", "message": "pong"}

Additional Support#

If these solutions don't resolve your issue:

1. Check GitHub Issues: Search for similar problems at github.com/upstash/context7/issues
2. Create a new issue: Include your:
   • Operating system and version
   • Node.js version (node --version)
   • MCP client and version
   • Configuration (remove sensitive data like API keys)
   • Error messages and logs
3. Join Discord: Get help from the community at upstash.com/discord

Additional Resources#

• Getting Started Guide
• Installation Instructions
• API Documentation
• Security & Privacy