npm error could not determine executable to run exa mcp

Not specified by the original author.

Fix npm error could not determine executable to run for exa-mcp-server

TL;DR

Point your MCP config at the server file with node directly instead of npx, or switch to the hosted remote server at https://mcp.exa.ai/mcp. The npx wrapper cannot resolve the package's entry point because the published bin field points inside a hidden .smithery directory, which npm refuses to execute.

The exact error:

npm error could not determine executable to run

Steps

1. Confirm this is the error

Run the package by hand in a terminal:

npx -y exa-mcp-server

Success check: if you see npm error could not determine executable to run, this skill applies. If instead you see a missing API key error, that is a different problem.

2. Find where npm installed the package

npm root -g

Success check: it prints a directory. Append /exa-mcp-server/.smithery/stdio/index.cjs to it. Verify the file exists:

ls "$(npm root -g)/exa-mcp-server/.smithery/stdio/index.cjs"

3. Point the MCP config at node directly

Edit claude_desktop_config.json (or your client's MCP config) and replace the npx entry with a direct node call:

{
  "mcpServers": {
    "exa": {
      "command": "node",
      "args": ["[global npm root]/exa-mcp-server/.smithery/stdio/index.cjs"],
      "env": { "EXA_API_KEY": "[your Exa API key]" }
    }
  }
}

Success check: save the file, fully restart the client. The exa server should start and its tools (web search, code context) appear in the tool list.

4. Alternative: use the hosted remote server instead

If you would rather skip the local install entirely, use the remote endpoint. For Claude Code:

claude mcp add exa -e EXA_API_KEY [your value] Exa API key] -- npx -y mcp-remote https://mcp.exa.ai/mcp

Success check: claude mcp list shows exa connected, and no local package install is needed.

When this applies

• You followed the standard npx -y exa-mcp-server setup for Claude Desktop, Cursor, or another MCP client and the server never starts.
• The terminal reproduces npm error could not determine executable to run for the package.

When it does not apply

• You get EXA_API_KEY environment variable is not set instead. That is an auth problem: put your key in the env block.
• You are using the remote https://mcp.exa.ai/mcp URL already. Do not mix the remote URL and the npx package in one entry; they are separate setups.

Tool compatibility

• exa-mcp-server npm package, versions publishing the .smithery/stdio/index.cjs layout
• npx / npm (Node.js 18+)
• Claude Desktop, Claude Code, Cursor, KiloCode

Why it happens

The published package's bin field points at .smithery/stdio/index.cjs, a path inside a hidden dot-directory. npm/npx will not resolve an executable out of a hidden directory, so it exits with the "could not determine executable" error even though the file is present and valid.

Edge cases

• bunx exa-mcp-server hits a related startup crash (SyntaxError at line 2 of the same file) on some versions; the node-direct workaround avoids that path too.
• If npm installed the package in a user-local prefix (.npm-global), the args path must use that prefix, not the system one. npm root -g tells you which.
• Some users report success pinning an older package version (e.g. [recipient email]) as a stopgap; the remote server option is the cleaner long-term move.

A user following the standard local stdio setup for the Exa MCP server ran npx -y exa-mcp-server and hit npm error could not determine executable to run. The issue thread diagnosed that the package's bin field points into the hidden .smithery directory, which npx cannot resolve. The verified workarounds from the thread: invoke node directly on the installed .smithery/stdio/index.cjs path in the MCP config, or drop the local package and use the hosted remote server https://mcp.exa.ai/mcp (e.g. via mcp-remote with the API key passed as EXAAPIKEY). Source: https://github.com/exa-labs/exa-mcp-server/issues/107

Not specified by the original author.

TL;DR

For "SyntaxError: Invalid or unexpected token": the shebang ended up on the second line of the published file instead of the first, so Node tries to parse it as JavaScript.

SyntaxError: Invalid or unexpected token

Steps

1. Running bunx exa-mcp-server@latest fails immediately with SyntaxError: Invalid or unexpected token at .smithery/index.cjs:2, pointing at the #!/usr/bin/env node line. The shebang ended up on the second line of the published file instead of the first, so Node tries to parse it as JavaScript. Node 22, via bunx on Linux.
2. The published npm tarball had the #!/usr/bin/env node shebang on line 2 of .smithery/index.cjs instead of line 1, which makes Node throw SyntaxError: Invalid or unexpected token. Fix: update to the latest npm package, where Exa corrected the shebang placement. If you need it working immediately, switch to the remote MCP server instead of the local install: remove the old config (claude mcp remove exa) and add the remote one (`claude mcp add exa -e EXAAPIKEY [your value] pointing at mcp.exa.ai/mcp), which the reporter confirmed works.

When to use

You are seeing this: Running bunx exa-mcp-server@latest fails immediately with SyntaxError: Invalid or unexpected token at.smithery/index.cjs:2, pointing at the #!/usr/bin/env node line. Use this skill when you run into "exa-mcp-server fails to start: SyntaxError Invalid or unexpected token in .smithery/index.cjs".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The shebang ended up on the second line of the published file instead of the first, so Node tries to parse it as JavaScript.

A user asked: Running bunx exa-mcp-server@latest fails immediately with SyntaxError: Invalid or unexpected token at .smithery/index.cjs:2, pointing at the #!/usr/bin/env node line. The shebang ended up on the second line of the published file instead of the first, so Node tries to parse it as JavaScript. Node 22, via bunx on Linux. The verified answer: The published npm tarball had the #!/usr/bin/env node shebang on line 2 of .smithery/index.cjs instead of line 1, which makes Node throw SyntaxError: Invalid or unexpected token. Fix: update to the latest npm package, where Exa corrected the shebang placement. If you need it working immediately, switch to the remote MCP server instead of the local install: remove the old config (claude mcp remove exa) and add the remote one (`claude mcp add exa -e EXAAPIKEY [your value] pointing at mcp.exa.ai/mcp), which the reporter confirmed works. Thread: https://vectle.com/threads/thrhRapXRujfG92RZ9EvCm2Q

Not specified by the original author.

TL;DR

Fix: update to the latest npm package, where Exa corrected the shebang placement.

Steps

1. Fix: update to the latest npm package, where Exa corrected the shebang placement.

When to use

Use this skill when you run into "exa-mcp-server fails to start: SyntaxError Invalid or unexpected token in .smithery/index.cjs".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Skill distilled from thread https://vectle.com/threads/thrhRapXRujfG92RZ9EvCm2Q