> ## Documentation Index
> Fetch the complete documentation index at: https://context7.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve common issues when setting up or using the Context7 MCP server

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

<Tip>
  **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](/resources/all-clients) for configuration examples.
</Tip>

## Common Fixes

### Use Latest Version

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

```json theme={null}
{
  "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`:

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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"
      ]
    }
  }
}
```

<Note>
  Replace `yourname` and the Node.js version (`v22.14.0`) with your actual username and installed
  Node.js version.
</Note>

## API and Connection Issues

### Rate Limiting

If you encounter rate limit errors:

* **Get an API key**: Sign up at [context7.com/dashboard](https://context7.com/dashboard) for higher rate limits
* **Add the API key to your configuration**:

```json theme={null}
{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "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:

```json theme={null}
{
  "headers": {
    "CONTEXT7_API_KEY": "YOUR_API_KEY"
  }
}
```

For stdio transport:

```json theme={null}
{
  "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](https://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

<AccordionGroup>
  <Accordion title="Linux/macOS" icon="terminal">
    ```bash theme={null}
    export https_proxy=http://proxy.example.com:8080
    export HTTPS_PROXY=http://proxy.example.com:8080
    ```

    With authentication:

    ```bash theme={null}
    export https_proxy=http://username:password@proxy.example.com:8080
    ```
  </Accordion>

  <Accordion title="Windows (Command Prompt)" icon="windows">
    ```cmd theme={null}
    set https_proxy=http://proxy.example.com:8080
    set HTTPS_PROXY=http://proxy.example.com:8080
    ```

    With authentication:

    ```cmd theme={null}
    set https_proxy=http://username:password@proxy.example.com:8080
    ```
  </Accordion>

  <Accordion title="Windows (PowerShell)" icon="windows">
    ```powershell theme={null}
    $env:https_proxy = "http://proxy.example.com:8080"
    $env:HTTPS_PROXY = "http://proxy.example.com:8080"
    ```
  </Accordion>
</AccordionGroup>

### Or Configure in MCP Settings

Add proxy directly to your MCP configuration:

```json theme={null}
{
  "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.

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

## Debugging Tips

### Enable Verbose Logging

Add debug output to your configuration:

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

### Test with MCP Inspector

Test your setup independently:

```bash theme={null}
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:

```bash theme={null}
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](https://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](https://upstash.com/discord)

## Additional Resources

* [Getting Started Guide](/overview)
* [Installation Instructions](https://github.com/upstash/context7#installation)
* [API Documentation](/api-guide)
* [Security & Privacy](/security/overview)