Troubleshooting

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

Quick Checklist#

• Confirm Node.js v20.18.1 or later 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 (recommended)
• 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", "--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"]    }  }}

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.18.1 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 the server status with claude mcp get context7, or start Claude Code with claude --debug to see MCP connection errors
• Try removing and re-adding the server

Configure HTTPS Proxy#

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

Allow these hosts through the proxy:

• The local stdio server (npx -y @upstash/context7-mcp) retrieves documentation from context7.com (the API base https://context7.com/api).
• A remote MCP client connects to mcp.context7.com, the hosted MCP endpoint. This is the URL in each client config and is separate from the API host the local server calls.

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