Windsurf Context7 - Fix npx not found issue (Linux)

When working with modern AI coding assistants like Windsurf, you might encounter an error when trying to set up Context7 MCP server:

failed to create mcp stdio client failed to start command:
exec npx executable not file not found in $path

This guide will help you understand what Context7 is, how to install it properly, and most importantly, how to fix this common issue on Linux systems.

What is Context7?

Context7 is an MCP (Model Context Protocol) server that enhances AI coding assistants by injecting up-to-date documentation into your prompts. When you add use context7 to your prompts, the server fetches current official documentation and code examples for libraries you’re using, ensuring you get accurate, version-specific code suggestions rather than outdated or hallucinated APIs.

Installing Context7 in Windsurf

To install Context7 in Windsurf, you need to add a configuration to your Windsurf MCP config file:

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

This configuration tells Windsurf to use the npx command to run the Context7 MCP server. However, many users encounter the “npx not found” error because Windsurf runs in a restricted environment that doesn’t inherit your shell’s PATH.

Here is the FIX

The root cause of this issue is that Windsurf can’t find the npx executable in your PATH. Here’s how to fix it on Ubuntu 24.04 with i3WM and Gnome DE.

Install LTS version if not already installed

nvm install --lts

Update your profile configuration

# file: $HOME/.profile

# Put at the end of the file
# 1) Set up NVM
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

# 2) (Optional) Install or switch to a default Node version
#    so that 'nvm version' won't return "N/A"
#    You only need to do this once (or whenever you want a new default).
#    We keep it here as some setups somehow forget we already set this.
nvm alias default lts/* # makes that LTS the default for new shells

# We export NVM
export NVM_DIR="$HOME/.nvm"
# 3) (Optional) Force‐add NPX (and npm, node) to PATH immediately
#    This is only needed if you want 'npx' before running 'nvm use'
#    which we definitely want for Windsurf to find it.
export PATH="$NVM_DIR/versions/node/$(nvm version)/bin:$PATH"

After adding these lines to your .profile file, log out and log back in, or source the file with source ~/.profile. This ensures that the npx executable is available in your PATH, even for applications like Windsurf that don’t inherit your shell environment.

Using Context7 in Windsurf

Once you’ve fixed the PATH issue and configured Context7, using it is straightforward:

1. Write your coding prompt in Windsurf
2. Add use context7 at the end of your prompt
3. Get enhanced results with up-to-date documentation

For example:

Create a basic Next.js project with app router. use context7

Context7 will identify that you’re asking about Next.js, fetch the latest documentation about the app router, and include that information in the context for the AI to generate more accurate code.

Alternative Solutions

If you’re still experiencing issues, you can try:

1. Using the full path to npx in your MCP configuration
2. Using Deno instead of Node.js (Context7 supports this too)
3. Creating a system-wide path configuration to ensure Windsurf sees the correct path

By properly configuring your environment to make npx available to Windsurf, you’ll be able to leverage the power of Context7 for more accurate and up-to-date coding assistance.