Install on Linux

Complete guide to install and configure ContextForge MCP on Linux (Ubuntu, Debian, Fedora, Arch, etc.)

Prerequisites

Node.js 18 or higher
Install via your package manager or use nvm (recommended)
Claude Desktop or Claude Code
Download Claude Desktop from claude.ai/download
ContextForge Account
Create a free account

Install Node.js (if needed)

Option A: Using nvm (Recommended)

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal, then install Node
nvm install --lts
nvm use --lts

Option B: Using package manager

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# Fedora
sudo dnf install nodejs npm

# Arch Linux
sudo pacman -S nodejs npm

Step 1: Install ContextForge MCP

Open your terminal and run:

npm install -g contextforge-mcp

Note: If you get permission errors, see the troubleshooting section below. Avoid using sudo with npm.

Step 2: Verify Installation

# Check if contextforge-mcp is installed
which contextforge-mcp

# Should output something like:
# /home/username/.nvm/versions/node/v20.x.x/bin/contextforge-mcp
# or /usr/local/bin/contextforge-mcp

Option A: Claude Code (CLI)

Quick Setup Wizard

Recommended

Run the interactive setup wizard:

npx contextforge-setup

Alternative: Manual Command

claude mcp add contextforge -s user -e CONTEXTFORGE_API_KEY=your-api-key-here -- contextforge-mcp

Verify Setup

# List configured MCPs
claude mcp list

# Or run verification
npx contextforge-setup --verify

Option B: Claude Desktop

1. Find the config file

The config file location on Linux:

~/.config/Claude/claude_desktop_config.json

2. Create the directory and file

# Create the directory if it doesn't exist
mkdir -p ~/.config/Claude

# Edit the config file
nano ~/.config/Claude/claude_desktop_config.json

3. Add ContextForge configuration

Add this content to the file:

{
  "mcpServers": {
    "contextforge": {
      "command": "contextforge-mcp",
      "env": {
        "CONTEXTFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Note: Replace your-api-key-here with your actual API key from your dashboard

4. Restart Claude Desktop

Close Claude Desktop completely and reopen it.

Updating ContextForge MCP

When a new version is available, you can update with:

npm install -g contextforge-mcp

If you run into issues or want a clean reinstall:

npm uninstall -g contextforge-mcp && npm install -g contextforge-mcp

After updating, restart Claude Desktop or your Claude Code session for changes to take effect.

Linux Troubleshooting

EACCES permission denied

Don't use sudo with npm. Instead, fix npm permissions:

# Create a directory for global packages
mkdir -p ~/.npm-global

# Configure npm to use it
npm config set prefix '~/.npm-global'

# Add to PATH in ~/.bashrc or ~/.zshrc
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Now install again
npm install -g contextforge-mcp

command not found: contextforge-mcp

Make sure npm's bin directory is in your PATH:

# Find where npm installs global packages
npm config get prefix

# Add to your PATH in ~/.bashrc or ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"

Node.js version too old

Some distros ship old Node.js versions. Use nvm to get the latest:

# Check current version
node --version

# If < 18, install nvm and update
nvm install --lts
nvm use --lts

Claude Desktop not available for Linux

If Claude Desktop isn't available for your distro, use Claude Code (CLI) instead. It works great on Linux!