MCP Setup Guide

Automatic Setup

The fastest way to set up Envark is using the built-in initialization command:

# Choose your IDE
npx envark init vscode    # VS Code
npx envark init claude    # Claude Desktop
npx envark init cursor    # Cursor
npx envark init windsurf  # Windsurf

This will:

Create the appropriate configuration directory
Generate the correct MCP configuration
Display instructions for the next steps

If a configuration file already exists, Envark will print the configuration to add manually rather than overwriting your existing setup.

Manual Configuration

If you prefer to configure manually or need to add Envark to an existing MCP setup, follow the instructions for your IDE:

VS Code
Claude Desktop
Cursor
Windsurf

VS Code with GitHub Copilot

Create MCP configuration

Create or edit .vscode/mcp.json in your project root:

.vscode/mcp.json

{
  "servers": {
    "envark": {
      "type": "stdio",
      "command": "npx",
      "args": ["envark"]
    }
  }
}

VS Code uses a project-local configuration (.vscode/mcp.json) rather than a global one.

Install Envark globally (optional)

For faster startup, install Envark globally:

npm install -g envark

Then update your configuration:

.vscode/mcp.json

{
  "servers": {
    "envark": {
      "type": "stdio",
      "command": "envark"
    }
  }
}

Reload VS Code

Press Cmd/Ctrl + Shift + P and run:

Developer: Reload Window

Verify integration

Open Copilot Chat and ask:

“Can you scan my project for environment variables?”

If configured correctly, Copilot will use the get_env_map tool.

Troubleshooting VS Code

Copilot doesn't see Envark tools

Check that .vscode/mcp.json exists in your project root
Verify the file has valid JSON syntax
Restart VS Code completely (close all windows)
Check VS Code’s Output panel for MCP errors

Command not found error

If using npx envark, ensure Node.js and npm are in your PATH:

which npx
node --version

If using global install, verify:

which envark
envark --version

Slow first run

The first time Envark runs via npx, it downloads the package. Subsequent runs use the cached version.For faster startup, install globally:

npm install -g envark

Claude Desktop (Claude Code)

Locate Claude config directory

The config file location depends on your OS:

macOS: ~/.claude/mcp.json
Linux: ~/.claude/mcp.json
Windows: %APPDATA%\Claude\mcp.json

Create or edit mcp.json

~/.claude/mcp.json

{
  "mcpServers": {
    "envark": {
      "command": "npx",
      "args": ["envark"]
    }
  }
}

If you have other MCP servers configured, add Envark to the existing mcpServers object.

Restart Claude Desktop

Completely quit and restart Claude Desktop to load the new configuration.

Test the integration

In a new conversation, ask:

“Please scan my current project for environment variables”

Claude should respond using Envark’s tools.

Using with -y flag

To avoid npx confirmation prompts, use the -y flag:

~/.claude/mcp.json

{
  "mcpServers": {
    "envark": {
      "command": "npx",
      "args": ["-y", "envark"]
    }
  }
}

Troubleshooting Claude

Claude doesn't see the tools

Verify the config file path is correct for your OS
Check JSON syntax with a validator
Ensure Claude Desktop is completely restarted
Check Claude’s developer console (if available) for errors

Permission denied errors

On macOS/Linux, ensure the config directory has correct permissions:

chmod 700 ~/.claude
chmod 600 ~/.claude/mcp.json

Cursor Editor

Locate Cursor config directory

macOS: ~/.cursor/mcp.json
Linux: ~/.cursor/mcp.json
Windows: %APPDATA%\Cursor\mcp.json

Create or edit mcp.json

~/.cursor/mcp.json

{
  "mcpServers": {
    "envark": {
      "command": "npx",
      "args": ["envark"]
    }
  }
}

Restart Cursor

Close all Cursor windows and reopen the editor.

Verify in Cursor Chat

Open Cursor Chat (Cmd/Ctrl + L) and ask:

“Scan my project for environment variables”

The AI should use Envark’s MCP tools to respond.

Global Install for Cursor

For better performance, install Envark globally:

npm install -g envark

Update configuration:

~/.cursor/mcp.json

{
  "mcpServers": {
    "envark": {
      "command": "envark"
    }
  }
}

Troubleshooting Cursor

Tools not available in chat

Confirm ~/.cursor/mcp.json exists and is valid JSON
Restart Cursor completely
Check that Node.js is installed and in PATH
Try running npx envark help in terminal to verify installation

Cursor hangs when calling tools

This may indicate Envark is scanning a very large project. Check:

Is your .gitignore properly configured?
Are node_modules or other large directories excluded?
Try running npx envark scan in terminal to see scan time

Windsurf IDE

Locate Windsurf config directory

macOS: ~/.windsurf/mcp.json
Linux: ~/.windsurf/mcp.json
Windows: %APPDATA%\Windsurf\mcp.json

Create or edit mcp.json

~/.windsurf/mcp.json

{
  "mcpServers": {
    "envark": {
      "command": "npx",
      "args": ["envark"]
    }
  }
}

Restart Windsurf

Completely quit and relaunch Windsurf.

Test integration

In Windsurf’s AI chat, ask:

“What environment variables are missing in my project?”

The AI should use get_missing_envs to answer.

Troubleshooting Windsurf

MCP server not loading

Verify config file location for your operating system
Check that the JSON is valid (use jsonlint or similar)
Ensure Windsurf has permission to execute npx
Try running Windsurf from terminal to see error messages

Advanced Configuration

Using a Specific Node Version

If you use a Node version manager (nvm, fnm, etc.), specify the full path:

{
  "mcpServers": {
    "envark": {
      "command": "/Users/yourname/.nvm/versions/node/v20.10.0/bin/npx",
      "args": ["envark"]
    }
  }
}

Setting a Working Directory

Some IDEs support setting a working directory for MCP servers:

{
  "mcpServers": {
    "envark": {
      "command": "npx",
      "args": ["envark"],
      "cwd": "/path/to/your/project"
    }
  }
}

Environment Variables

You can pass environment variables to Envark:

{
  "mcpServers": {
    "envark": {
      "command": "npx",
      "args": ["envark"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

Verifying Your Setup

After configuration, verify Envark is working:

Test via AI Assistant

Ask your AI assistant:

“Can you list the available MCP tools?”

You should see Envark’s 9 tools listed.

Test via Terminal

Run Envark directly to ensure it works:

npx envark scan

You should see a list of environment variables from your project.

Check MCP Logs

Most IDEs log MCP server activity. Check:

VS Code: Output panel → “MCP” or “Language Server”
Claude Desktop: Help → Developer Console
Cursor: View → Output → “MCP”

Common Issues

Error: Cannot find module 'envark'

This means npx couldn’t download or find Envark. Solutions:

Install globally: npm install -g envark
Clear npm cache: npm cache clean --force
Use full npx path: /usr/local/bin/npx envark

MCP server times out

Envark might be scanning a very large project:

Check that .gitignore excludes node_modules, .git, etc.
Run npx envark scan manually to see scan time
Increase timeout in IDE settings (if available)

Tools return empty results

This usually means Envark is running in the wrong directory:

Verify your IDE opened the correct project folder
Check the cwd setting in MCP config
Run npx envark scan in your project directory to verify results

Permission denied on macOS/Linux

Fix file permissions:

chmod +x $(which npx)
chmod 644 ~/.claude/mcp.json  # or ~/.cursor/mcp.json, etc.

Get Started

Core Features

CLI Reference

MCP Integration

Guides

MCP Setup Guide

Automatic Setup

Manual Configuration

VS Code with GitHub Copilot

Troubleshooting VS Code

Claude Desktop (Claude Code)

Using with -y flag

Troubleshooting Claude

Cursor Editor

Global Install for Cursor

Troubleshooting Cursor

Windsurf IDE

Troubleshooting Windsurf

Advanced Configuration

Using a Specific Node Version

Setting a Working Directory

Environment Variables

Verifying Your Setup

Test via AI Assistant

Test via Terminal

Check MCP Logs

Common Issues

Next Steps

Tool Reference

Usage Examples

Build docs developers (and LLMs) love

Get Started

Core Features

CLI Reference

MCP Integration

Guides

​Automatic Setup

​Manual Configuration

​VS Code with GitHub Copilot

​Troubleshooting VS Code

​Claude Desktop (Claude Code)

​Using with -y flag

​Troubleshooting Claude

​Cursor Editor

​Global Install for Cursor

​Troubleshooting Cursor

​Windsurf IDE

​Troubleshooting Windsurf

​Advanced Configuration

​Using a Specific Node Version

​Setting a Working Directory

​Environment Variables

​Verifying Your Setup

​Test via AI Assistant

​Test via Terminal

​Check MCP Logs

​Common Issues

​Next Steps

Tool Reference

Usage Examples

Build docs developers (and LLMs) love

Automatic Setup

Manual Configuration

VS Code with GitHub Copilot

Troubleshooting VS Code

Claude Desktop (Claude Code)

Using with -y flag

Troubleshooting Claude

Cursor Editor

Global Install for Cursor

Troubleshooting Cursor

Windsurf IDE

Troubleshooting Windsurf

Advanced Configuration

Using a Specific Node Version

Setting a Working Directory

Environment Variables

Verifying Your Setup

Test via AI Assistant

Test via Terminal

Check MCP Logs

Common Issues

Next Steps