Troubleshooting - Context7 MCP

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

Quick Checklist

Confirm Node.js v18+ 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

Skip Node.js issues entirely: Use the remote server connection instead of local npx. Most MCP clients support connecting to https://mcp.context7.com/mcp directly, which requires no local Node.js installation. See All MCP Clients for configuration examples.

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/[email protected]"]
    }
  }
}

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 v18 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"
      ]
    }
  }
}

Replace yourname and the Node.js version (v22.14.0) with your actual username and installed Node.js version.

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": {
        "CONTEXT7_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Authentication Errors

If you see 401 Unauthorized errors:

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

For HTTP transport:

{
  "headers": {
    "CONTEXT7_API_KEY": "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:

Verify the library ID format is correct: /owner/repo or /owner/repo/version
Search for the library first using resolve-library-id tool
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

Linux/macOS

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

With authentication:

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

Windows (Command Prompt)

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

With authentication:

set https_proxy=http://username:[email protected]:8080

Windows (PowerShell)

$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.

After updating proxy settings, run curl https://mcp.context7.com/ping to confirm outbound connectivity before restarting your IDE.

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:

Check GitHub Issues: Search for similar problems at github.com/upstash/context7/issues
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
Join Discord: Get help from the community at upstash.com/discord

​Quick Checklist

​Common Fixes

​Use Latest Version

​Module Not Found / Use Alternative Runtimes

​ESM Resolution Issues

​TLS/Certificate Issues

​Node.js Version

​Platform-Specific Issues

​Windows Issues

​Request Timeout Errors

​macOS Issues

​Request Timeout Errors

​API and Connection Issues

​Rate Limiting

​Authentication Errors

​Library Not Found

​MCP Client-Specific Issues

​Cursor

​VS Code

​Claude Code

​Configure HTTPS Proxy

​Set Environment Variables

​Or Configure in MCP Settings

​Debugging Tips

​Enable Verbose Logging

​Test with MCP Inspector

​Check Server Status

​Additional Support

​Additional Resources

Quick Checklist

Common Fixes

Use Latest Version

Module Not Found / Use Alternative Runtimes

ESM Resolution Issues

TLS/Certificate Issues

Node.js Version

Platform-Specific Issues

Windows Issues

Request Timeout Errors

macOS Issues

Request Timeout Errors

API and Connection Issues

Rate Limiting

Authentication Errors

Library Not Found

MCP Client-Specific Issues

Cursor

VS Code

Claude Code

Configure HTTPS Proxy

Set Environment Variables

Or Configure in MCP Settings

Debugging Tips

Enable Verbose Logging

Test with MCP Inspector

Check Server Status

Additional Support

Additional Resources