Linux で Claude の MCP を設定｜CLI 接続と config 配置

Linux では Claude Code CLI が MCP の主役

MCP は、ファイルシステムや GitHub、データベースといった外部ツールを Claude から直接読み書きできるようにするオープン標準です。接続先を増やすほど、別ツールから情報をコピペする手間が消えていきます。

ただし接続の「入口」となるアプリは OS で異なります。公式の Claude デスクトップアプリは macOS と Windows のみ提供で、Linux 版は配布されていません(出典: https://modelcontextprotocol.io/docs/develop/connect-local-servers)。そのため Linux では、ターミナルで動く Claude Code CLI に MCP サーバーを追加するのが標準ルートになります。

Claude Code は HTTP・stdio・SSE・WebSocket という複数の通信方式に対応し、数百種類の外部ツールへ接続できます(出典: https://code.claude.com/docs/en/mcp)。Linux のディストリビューション(Ubuntu / Debian / Arch / Fedora など)を問わず、CLI さえ入っていれば同じコマンドで設定できるのが利点です。

事前準備:Node.js と Claude Code の確認

stdio 型のローカルサーバーの多くは Node.js の npx で起動します。まず実行環境を確認しましょう。

1. Node.js の有無を確認する。ターミナルで node --version を実行し、LTS 版が入っているか確かめます。未導入なら https://nodejs.org/ から LTS を入れます。
2. Python 製サーバー(uvx 起動など)を使う予定があれば、Python と uv も用意します。
3. Claude Code 本体を確認する。claude --version が通れば導入済みです。未導入の場合は Linux 向けの導入手順(npm 版・公式インストーラ版)で先に CLI を入れておきます。

npx がグローバルに通っていないと後述の spawn ENOENT で失敗するため、which npx でパスが返ることもあわせて確認しておくと安全です。

MCP サーバーを追加する 3 つの方式

Claude Code への追加は、通信方式に応じて主に 3 通りです。共通の注意点として、オプション(--transport --env --scope など)はサーバー名より前に置き、-- 以降に実行コマンドを書きます。

リモート HTTP サーバーを追加する

クラウド型サービスへの接続は HTTP が推奨です。

# 基本構文
claude mcp add --transport http <name> <url>

# 例: Notion に接続
claude mcp add --transport http notion https://mcp.notion.com/mcp

認証が必要なサービスは、接続後に Claude Code 内で /mcp を実行するとブラウザで OAuth ログインに進めます。

ローカル stdio サーバーを追加する

自分の Linux マシン上でプロセスとして動く方式です。ファイル操作や独自スクリプトなど、ローカル資源に直接触れる用途に向きます。

# 基本構文(-- 以降が実行コマンド)
claude mcp add [options] <name> -- <command> [args...]

# 例: 環境変数を渡して Airtable サーバーを追加
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

JSON 設定から一括追加する

サーバー提供元が JSON 設定を配っている場合は、そのまま流し込めます。

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

ローカル stdio サーバーを Linux で動かす(Filesystem 例)

もっとも需要が高いのが、ホームディレクトリ配下のファイルを Claude に読み書きさせる Filesystem サーバーです。Linux での追加から動作確認までの流れは次のとおりです。

1. Filesystem サーバーを stdio で追加する。アクセスを許すディレクトリを引数で明示します。

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

2. 登録を確認する。claude mcp list に追加したサーバーが並ぶか見ます。
3. 接続状態を見る。Claude Code を起動し、対話中に /mcp を実行するとサーバーごとのツール数と接続状況が表示されます。
4. 実際に依頼する。「Downloads 内の画像を一覧にして」などと頼み、操作のたびに表示される承認ダイアログで許可します。

ディレクトリ指定は絶対パスが安全です。サーバーは自分のユーザー権限で動くため、許可するのは Claude に触らせてよいフォルダだけに絞ります(出典: https://modelcontextprotocol.io/docs/develop/connect-local-servers)。

.mcp.json と設定の保存先(3 つのスコープ)

設定をどこに保存するかは --scope で選びます。チームで共有するか、自分専用にするかで使い分けます(出典: https://code.claude.com/docs/en/mcp)。

チームで配布したい場合は project スコープを選び、リポジトリに .mcp.json をコミットします。標準的な書式は次のとおりです。

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

.mcp.json では ${VAR} や ${VAR:-default} の形で環境変数を展開できます。マシンごとに異なるパスや API キーを各自の環境変数に逃がしつつ、設定そのものは共有できる仕組みです。なお project スコープのサーバーは、初回利用時に承認を求められます。

非公式 Claude デスクトップを Linux で使う場合

どうしても GUI が欲しい場合、WINE 経由や有志ビルド(.deb / AUR など)の非公式デスクトップ版を使う選択肢があります。この系統では設定ファイルの場所が CLI と異なり、Linux では次のパスを使います。

~/.config/Claude/claude_desktop_config.json

このファイルに mcpServers を記述し、アプリを完全に終了してから再起動すると反映されます。記述例は CLI の .mcp.json と同じ command / args / env 構造です(出典: https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)。

ただし非公式ビルドは動作保証がなく、アップデート追従も自己責任です。安定運用を重視するなら、まずは公式サポート対象の Claude Code CLI を主軸に据えるのが堅実です。

Linux でよくあるトラブルと対処

設定どおりでもサーバーが繋がらないときは、Linux 特有の落とし穴をこの順で確認します。

1. spawn claude ENOENT が出る場合。実行ファイルが PATH に無いのが原因です。which claude でフルパスを調べ、設定の command に絶対パスを書きます。npx 系サーバーも同様にパス不通を疑います。
2. サーバーが一覧に出ない場合。.mcp.json(または claude_desktop_config.json)の JSON 構文を点検し、パスが絶対パスになっているか確認します。
3. サーバー単体で起動するか試す。npx -y @modelcontextprotocol/server-filesystem ~/Documents を直接ターミナルで実行し、エラー文を読みます。
4. 起動が遅くてタイムアウトする場合。MCP_TIMEOUT 環境変数で待ち時間を延ばせます(例: MCP_TIMEOUT=10000 claude で 10 秒)。
5. 設定済みサーバーの状態を見る。claude mcp get <name> で個別の詳細を、claude mcp remove <name> で削除を行います。

なお Claude Desktop の設定を取り込む claude mcp add-from-claude-desktop は macOS と WSL のみ対応で、素の Linux では使えません。Linux ではここまでの claude mcp add を直接使うのが確実です。

まとめ

Linux における MCP 設定は、「公式デスクトップが無いぶん、Claude Code CLI に寄せる」のが要点です。

• 接続は claude mcp add が基本。HTTP はリモート、-- 付きの stdio はローカルサーバー向け。
• 設定は local / project / user の 3 スコープ。共有は .mcp.json(project)、個人は ~/.claude.json。
• 非公式デスクトップ版を使うなら config は ~/.config/Claude/claude_desktop_config.json。
• 繋がらないときは PATH(which claude)・絶対パス・サーバー単体起動・MCP_TIMEOUT を順に確認。

まずは Filesystem サーバーを 1 つ追加し、/mcp でツールが見えるところまで通してみると、Linux 環境での MCP 接続の感覚がつかめます。

出典

• Claude Code 公式ドキュメント「Connect Claude Code to tools via MCP」: https://code.claude.com/docs/en/mcp
• Model Context Protocol 公式「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