Setting Up Claude MCP on Linux | CLI Connection and Config File Placement

Claude Code CLI Is the Core of MCP on Linux

MCP is an open standard that allows Claude to directly read from and write to external tools such as file systems, GitHub, and databases. The more connections you add, the less time you spend copying and pasting information from other tools.

However, the "entry point" application differs by OS. The official Claude desktop app is only available for macOS and Windows — no Linux version is distributed (source: https://modelcontextprotocol.io/docs/develop/connect-local-servers). On Linux, the standard route is therefore to add MCP servers to the Claude Code CLI, which runs in the terminal.

Claude Code supports multiple communication methods — HTTP, stdio, and SSE — and can connect to hundreds of external tools (source: https://code.claude.com/docs/en/mcp). Note that while WebSocket is a transport type in the MCP specification, it is not a valid value for claude mcp add --transport; the three actually usable options are http, stdio, and sse. Regardless of your Linux distribution (Ubuntu, Debian, Arch, Fedora, etc.), as long as the CLI is installed, the same commands work everywhere.

Prerequisites: Verifying Node.js and Claude Code

Many stdio-type local servers are launched via Node.js npx. Start by verifying your runtime environment.

1. Check whether Node.js is installed. Run node --version in the terminal to confirm an LTS version is present. If it is not, install the LTS version from https://nodejs.org/.
2. If you plan to use Python-based servers (launched with uvx), also prepare Python and uv.
3. Verify the Claude Code binary. If claude --version succeeds, it is already installed. If not, install the CLI for Linux first (npm version or the official installer).

If npx is not available globally, the spawn ENOENT error described later will occur. It is worth also running which npx to confirm the path is returned.

Three Methods for Adding an MCP Server

There are mainly three methods for adding servers to Claude Code, depending on the communication type. A key point common to all: options such as --transport, --env, and --scope must be placed before the server name, and the execution command is written after --.

Adding a Remote HTTP Server

HTTP is the recommended method for connecting to cloud-based services.

# Basic syntax
claude mcp add --transport http <name> <url>

# Example: connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

For services that require authentication, run /mcp inside Claude Code after connecting to proceed to OAuth login in your browser.

Adding a Local stdio Server

This method runs a process on your local Linux machine. It is suited for use cases that need direct access to local resources, such as file operations or custom scripts.

# Basic syntax (execution command follows --)
claude mcp add [options] <name> -- <command> [args...]

# Example: add an Airtable server with an environment variable
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

The syntax is the same for registering Python-based servers launched with uvx — just replace -- npx with -- uvx.

# Example: add a Python-based server via uvx (no API key required)
claude mcp add --transport stdio <name> -- uvx <package-name>

# Example: pass an API key via --env when required
claude mcp add --transport stdio --env API_KEY=YOUR_KEY <name> -- uvx <package-name>

Bulk Import from a JSON Configuration

If the server provider supplies a JSON configuration, you can pipe it in directly.

claude mcp add-json local-weather \
  '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

Running a Local stdio Server on Linux (Filesystem Example)

The most commonly needed server is the Filesystem server, which lets Claude read and write files under your home directory. Here is the full flow from adding it on Linux to verifying it works.

1. Add the Filesystem server via stdio. Explicitly specify the directories you want to allow access to as arguments.

   claude mcp add --transport stdio filesystem \
     -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Downloads
   

2. Verify the registration. Check that the added server appears in claude mcp list.
3. Check the connection status. Launch Claude Code and run /mcp during a session to see the tool count and connection status for each server.
4. Make a request. Ask something like "List the images inside Downloads" and approve the permission dialog that appears for each operation.

Absolute paths are safer for directory specifications. Because the server runs under your user permissions, limit access to only the folders you are comfortable letting Claude touch (source: https://modelcontextprotocol.io/docs/develop/connect-local-servers).

.mcp.json and Config Storage Locations (Three Scopes)

You choose where settings are saved with --scope. Use different scopes depending on whether you want to share settings with a team or keep them personal (source: https://code.claude.com/docs/en/mcp).

To distribute settings to your team, choose the project scope and commit .mcp.json to the repository. The standard format is as follows.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/Documents"],
      "env": {}
    }
  }
}

In .mcp.json, environment variables can be expanded in the form ${VAR} or ${VAR:-default}. This lets you keep paths and API keys that differ per machine in each user's own environment variables while sharing the configuration itself. Note that project-scoped servers require approval on first use.

Using the Unofficial Claude Desktop on Linux

If you really want a GUI, you can use an unofficial desktop build via WINE or a community build (.deb, AUR, etc.). With these, the configuration file location differs from the CLI, and on Linux the following path is used.

~/.config/Claude/claude_desktop_config.json

Write mcpServers to this file, then fully quit the app and restart it for the changes to take effect. The format uses the same command / args / env structure as the CLI's .mcp.json (source: https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop).

However, unofficial builds come with no guarantee of functionality, and keeping up with updates is your own responsibility. If stability is a priority, it is more practical to rely on the officially supported Claude Code CLI as your primary tool.

Common Linux Troubleshooting

If the server does not connect even when the configuration looks correct, check for these Linux-specific pitfalls in order.

1. If spawn claude ENOENT appears: the executable is not on the PATH. Run which claude to find the full path and write the absolute path in the command field of the configuration. The same PATH issue applies to npx-based servers.
2. If the server does not appear in the list: inspect the JSON syntax in .mcp.json (or claude_desktop_config.json) and confirm that paths are absolute paths.
3. Try launching the server on its own: run npx -y @modelcontextprotocol/server-filesystem ~/Documents directly in the terminal and read any error messages.
4. If startup is slow and times out: you can extend the wait time with the MCP_TIMEOUT environment variable (e.g., MCP_TIMEOUT=10000 claude for 10 seconds).
5. To inspect a configured server: use claude mcp get <name> for individual details and claude mcp remove <name> to delete it.

Note that claude mcp add-from-claude-desktop, which imports Claude Desktop settings, only works on macOS and WSL — it is not available on bare Linux. On Linux, using claude mcp add directly as described above is the reliable approach.

Summary

The key to MCP configuration on Linux is: since there is no official desktop app, lean on the Claude Code CLI.

• The basic command is claude mcp add. Use HTTP for remote servers and stdio with -- for local servers.
• Settings have three scopes: local, project, and user. Use .mcp.json (project) for sharing, and ~/.claude.json for personal use.
• If using an unofficial desktop build, the config is at ~/.config/Claude/claude_desktop_config.json.
• When a connection fails, check in order: PATH (which claude), absolute paths, launching the server standalone, and MCP_TIMEOUT.

Start by adding one Filesystem server and verifying that the tools appear in /mcp — that will give you a solid feel for MCP connections in a Linux environment.

Sources

• Claude Code official documentation "Connect Claude Code to tools via MCP": https://code.claude.com/docs/en/mcp
• Model Context Protocol official "Connect to local MCP servers": https://modelcontextprotocol.io/docs/develop/connect-local-servers
• Claude Help Center "Getting Started with Local MCP Servers": https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop