Category: Computing

⚠️ Important Warnings and Prerequisites

Before you begin:

• Backup any important data – always a good idea
• System requirements: Ubuntu 20.04+ or Debian 11+/Debian-based distro (I’m running on Pop!_OS 22.04 LTS with Nvidia); Anthropic doesn’t publish RAM, disk space, or CPU requirements, but third-party online posts recommend 8GB ~ 32GB RAM
• Terminal comfort: This guide involves using the terminal (https://ubuntu.com/tutorials/command-line-for-beginners), but all commands are provided step-by-step

What You’ll Install

• Claude Desktop: The desktop application for Claude AI
• Node.js via NVM: JavaScript runtime needed for MCP servers
• Desktop Commander MCP: Allows Claude to interact with your desktop (take screenshots, run commands, etc.)

Step 1: Update Your System

First, let’s make sure your system packages are up to date.

1. Open your terminal (https://help.ubuntu.com/community/UsingTheTerminal) by pressing Ctrl+Alt+T

2. Update your package lists and upgrade existing packages:

sudo apt update && sudo apt upgrade -y

What this does: sudo (https://www.sudo.ws/about/) gives you administrator privileges, apt (https://ubuntu.com/server/docs/package-management) is Ubuntu/Debian’s package manager, and this ensures your system has the latest security updates.

Step 2: Install Essential Dependencies

Install tools we’ll need for the installation process:

sudo apt install -y curl wget gnupg2 software-properties-common

What these tools do:

• curl (https://curl.se/): Downloads files from the internet
• wget (https://www.gnu.org/software/wget/): Alternative download tool
• gnupg2 (https://gnupg.org/): Handles cryptographic signatures for security
• software-properties-common: Manages software repositories

Step 3: Install Node.js Using NVM

We need Node.js (https://nodejs.org/) to run MCP servers. We’ll use NVM (Node Version Manager) (https://github.com/nvm-sh/nvm) which makes managing Node.js versions easier.

1. Download and install NVM if you don’t already have it installed:

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

2. Restart your terminal or reload your shell configuration:

source ~/.bashrc

3. Verify NVM was installed:

nvm --version

4. Install the latest LTS (https://nodejs.org/en/about/previous-releases) version of Node.js:

nvm install --lts
nvm use --lts

5. Verify Node.js and npm (https://www.npmjs.com/) are working:

node --version
npm --version

You should see version numbers after both commands.

Step 4: Download and Install Claude Desktop

Note: We’re using a community-maintained package since Anthropic (https://docs.anthropic.com/en/docs/claude-code/getting-started) doesn’t officially support Linux yet.

1. Visit the Claude Desktop for Debian GitHub repository (https://github.com/aaddrick/claude-desktop-debian) in your web browser. (Unfortunately this package is deprecated, BUT there are a couple of active forks, so if you’re reading this in later months and the package is broken, check the active forks.)

2. Go to the “Releases” section and download the latest .deb file (https://en.wikipedia.org/wiki/Deb_(file_format))

3. Navigate to your Downloads folder in the terminal:

cd ~/Downloads

4. Install the downloaded package (replace filename.deb with the actual filename):

sudo dpkg -i claude-desktop_*.deb

5. If you encounter dependency issues, fix them with:

sudo apt install -f

What this does: dpkg (https://wiki.debian.org/dpkg) is the low-level package installer for Debian/Ubuntu systems. The -f flag fixes broken dependencies.

Step 5: Create Claude Desktop Configuration Directory

Claude Desktop needs a configuration file to know about MCP servers.

1. Create the configuration directory:

mkdir -p ~/.config/Claude

What this does: mkdir -p (https://www.gnu.org/software/coreutils/manual/html_node/mkdir-invocation.html) creates directories and any necessary parent directories. The ~ symbol represents your home directory (https://tldp.org/LDP/abs/html/special-chars.html).

Step 6: Test Desktop Commander MCP Server

Before configuring Claude Desktop, let’s make sure the Desktop Commander MCP server works.

1. Test the MCP server directly:

npx @wonderwhy-er/desktop-commander@latest

You should see output like:

Loading schemas.ts
Loading server.ts
Setting up request handlers...
[desktop-commander] Initialized FilteredStdioServerTransport

2. Press Ctrl+C to stop the test server.

What this does: npx (https://docs.npmjs.com/cli/v7/commands/npx) runs Node.js packages without permanently installing them. This tests that the MCP server can start properly.

Step 7: Configure Claude Desktop for MCP

Now we’ll create the configuration file that tells Claude Desktop about our MCP server.

1. Create the configuration file:

nano ~/.config/Claude/claude_desktop_config.json

What this does: opens nano (https://www.nano-editor.org/) a text editor for the terminal.

2. Copy and paste this configuration into the file:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "@wonderwhy-er/desktop-commander@latest"
      ]
    }
  }
}

3. Save and exit nano:
   • Press Ctrl+X
   • Press Y to confirm saving
   • Press Enter to confirm the filename

Step 8: Launch Claude Desktop

1. Start Claude Desktop from the graphical applications menu, or run from terminal:

claude-desktop

2. Sign in with your Anthropic account when prompted

3. Look for MCP indicators in the interface – you should see evidence that the Desktop Commander server is connected

Step 9: Test Your MCP Setup

1. In Claude Desktop, try asking Claude to take a screenshot:

   “Can you take a screenshot of my current desktop?”

2. Or ask Claude to check system information:

   “What’s my current working directory and what files are in my home folder?”

If Claude can respond to these requests with actual information about your system, congratulations! Your MCP setup is working.

Troubleshooting Common Issues

Issue: “Cannot find module” errors

Solution: This usually means there’s a problem with literal command substitution in your config file:

1. Check your config file for any "$(which npx)" strings:

cat ~/.config/Claude/claude_desktop_config.json

2. If you see "$(which npx)" anywhere, replace it with just "npx" – the simple form works when Node.js is properly installed via NVM

Issue: Claude Desktop won’t start

Solution: Check if all dependencies are installed:

sudo apt install -f
sudo apt update

Issue: MCP server not connecting

Solution: First, verify that Desktop Commander itself is working:

1. Test the MCP server directly to confirm it’s functioning:

npx @wonderwhy-er/desktop-commander@latest

You should see output like:

Loading schemas.ts
Loading server.ts
Setting up request handlers...
[desktop-commander] Initialized FilteredStdioServerTransport
Loading configuration...
Configuration loaded successfully
Connecting server...
Server connected successfully

2. If that works (press Ctrl+C to stop it), then the issue is with Claude Desktop’s configuration, not the MCP server itself

3. Check Claude Desktop logs for connection errors – these are usually in the application’s output when started from terminal

Security Considerations

Important: The Desktop Commander MCP gives Claude significant access to your system, including:

• Taking screenshots
• Running terminal commands
• Accessing files

Best practices:

• Only use this setup on personal machines, not shared computers
• Review what you’re asking Claude to do before confirming actions
• Consider creating a separate user account for testing MCP functionality
• Keep your system updated with security patches

Keeping Everything Updated

Update Node.js

nvm install --lts
nvm use --lts

Update MCP packages

The @latest tag in our configuration automatically uses the newest version, but you can manually update:

npm update -g @wonderwhy-er/desktop-commander

Update Claude Desktop

Check the project forks on GitHub periodically for new .deb package releases and install them using the same dpkg process.

Uninstalling (If Needed)

Remove Claude Desktop

sudo apt remove claude-desktop

Remove Node.js and NVM

nvm uninstall node
rm -rf ~/.nvm

Remove the NVM lines from your ~/.bashrc file using a text editor.

Remove configuration files

rm -rf ~/.config/Claude

Next Steps

Now that you have Claude Desktop with MCP working, you can:

1. Explore other MCP servers: Check the MCP ecosystem (https://github.com/modelcontextprotocol) for additional tools
2. Customize your setup: Add more MCP servers to your configuration
3. Learn more about MCP: Read the official MCP documentation (https://modelcontextprotocol.io/docs)

Remember to always be cautious when giving AI systems access to your computer, and enjoy exploring the powerful combination of Claude AI with your Linux desktop.

Credits and Resources

• Claude Desktop for Debian: Community package by aaddrick, deprecated recently but forked (https://github.com/aaddrick/claude-desktop-debian)
• Desktop Commander MCP: Created by @wonderwhy-er (https://github.com/wonderwhy-er/desktop-commander) – Thanks, Dmitry, for your help on Discord confirming that it was indeed the config file
• Model Context Protocol: Developed by Anthropic (https://modelcontextprotocol.io/)

This guide was created based on real troubleshooting experience and community feedback. If you encounter issues, check the GitHub repositories for these projects or ask for help in Discord/Linux communities.