CodeCraft Lab

MCPサーバーをローカル環境で設定する

MCPの概念から、ローカル環境でのMCPサーバー設定、動作確認までを解説します

ふつう9分で読了
MCP設定ローカル環境

はじめに

Claude Codeは単体でも強力ですが、MCP（Model Context Protocol）を使うことで、データベースやAPI、外部サービスと直接連携できるようになります。たとえば「GitHub上のIssueを読んで修正する」「データベースのスキーマを確認してクエリを書く」といった作業が、Claude Codeの会話の中でシームレスに行えるようになります。

このレシピでは、MCPの基本概念を理解したうえで、ローカル環境にMCPサーバーを設定し、動作確認するまでの手順を解説します。

MCPとは

MCP（Model Context Protocol）は、AIツールと外部のデータソースやサービスを接続するためのオープンソースの標準プロトコルです。MCPサーバーを接続すると、Claude Codeはそのサーバーが提供する「ツール」を使えるようになります。

たとえば、データベースのMCPサーバーを接続すれば、Claude Codeが直接SQLクエリを実行できます。GitHub MCPサーバーを接続すれば、IssueやPRの操作がClaude Codeの会話内で完結します。これまでブラウザとターミナルを行き来していた作業が、ひとつの対話に統合されるイメージです。

MCPでできること

MCPサーバーを接続すると、以下のような操作がClaude Codeの会話内から直接行えます:

  • Issue管理ツールからチケットの内容を読み取り、実装してPRを作成する
  • データベースに接続してスキーマを確認し、クエリを実行する
  • Slackチャンネルにメッセージを送信する
  • WebページやAPIからデータを取得する

MCPサーバーの種類

MCPサーバーには大きく2つのタイプがあります。

タイプ説明適した用途
リモート（HTTP）サーバークラウド上でホストされたサーバーにURLで接続するSaaS連携（GitHub、Sentry等）
ローカル（stdio）サーバー自分のマシン上でプロセスとして起動するファイルシステム操作、ローカルDB接続

このレシピでは、ローカル（stdio）サーバーの設定を中心に解説します。

セットアップ手順

ここでは、Playwright MCPサーバー（ブラウザ操作ツール）を例にして、MCPサーバーのセットアップ手順を説明します。

前提条件を確認する

MCPサーバーの多くはNode.jsで動作します。Node.js 18以降がインストールされていることを確認してください。

node --version

Claude Codeがインストール済みで、認証が完了していることも確認します。

claude --version

MCPサーバーを追加する

claude mcp add コマンドでMCPサーバーを登録します。

claude mcp add playwright -- npx -y @playwright/mcp@latest

コマンドの各部分の意味は以下のとおりです。

claude mcp add はClaude CodeにMCPサーバーを登録するコマンドです。playwright はサーバーに付ける名前（任意の名前でOK）、-- の後ろがサーバーの起動コマンド、npx -y @playwright/mcp@latest がPlaywright MCPサーバーを起動するコマンドです。

接続を確認する

サーバーが正しく登録されたか確認します。

claude mcp list

ステータスが Connected と表示されれば成功です。初回は npx がパッケージをダウンロードするため、少し時間がかかることがあります。

動作を確認する

Claude Codeを起動して、MCPサーバーを使った操作を試します。

claude

セッション内で以下のように指示してみましょう。

playwrightを使って https://example.com を開いて、ページタイトルを教えてください

初回はツールの使用許可を求められるので、承認してください。

.mcp.json で設定を管理する

CLIコマンドの代わりに、プロジェクトルートに .mcp.json ファイルを作成して設定を管理することもできます。この方法はチームでの設定共有に便利です。

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}
設定のスコープ

MCPサーバーの設定は3つのスコープで管理できます:

  • local（デフォルト）: 自分だけ、現在のプロジェクトのみ
  • project: .mcp.jsonをリポジトリにコミットしてチーム共有
  • user: 自分のすべてのプロジェクトで利用可能

環境変数を使った設定も可能です。APIキーなどの機密情報はこの方法で渡しましょう。

{
  "mcpServers": {
    "my-api-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "my-mcp-server"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

セッション内での管理

Claude Codeのセッション内では、/mcp コマンドでMCPサーバーの状態を確認・管理できます。

/mcp

このコマンドで、各サーバーの接続状態、利用可能なツール数、認証状態を確認できます。OAuth認証が必要なリモートサーバーの場合は、ここからブラウザ認証に進むこともできます。

トラブルシューティング

「Failed to connect」と表示される

サーバーの起動コマンドが正しいか確認してください。ターミナルで直接コマンドを実行して、エラーが出ないか試しましょう。

npx -y @playwright/mcp@latest

Node.jsのバージョンが古い場合や、ネットワーク環境によるnpmレジストリへの接続問題が原因であることが多いです。

接続がタイムアウトする

初回起動時はパッケージのダウンロードに時間がかかることがあります。MCP_TIMEOUT 環境変数でタイムアウト値を延長できます。

MCP_TIMEOUT=60000 claude

ツールが表示されない

/mcp でサーバーは接続済みなのにツールが表示されない場合は、必要な環境変数が不足している可能性があります。サーバーのドキュメントを確認し、env フィールドで必要な変数を設定してください。

セキュリティに関する注意事項

MCPサーバーのセキュリティ

MCPサーバーはClaude Codeに強力な権限を与えるため、以下の点に注意してください:

  • 信頼できるソースのMCPサーバーのみを使用する
  • APIキーやトークンは環境変数で渡し、.mcp.jsonにハードコードしない
  • .mcp.jsonをコミットする場合、機密情報が含まれていないか確認する
  • データベース接続には読み取り専用のユーザーを使うことを検討する

プロジェクトスコープの.mcp.jsonからサーバーを読み込む場合、Claude Codeは初回利用時に承認を求めます。これは、リポジトリをクローンしただけで意図しないプロセスが起動するのを防ぐための仕組みです。

応用テクニック

複数のMCPサーバーを同時に利用する

.mcp.json に複数のサーバーを定義することで、1つのセッションから複数のサービスに接続できます。

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
    }
  }
}

リモートサーバーへの接続

SaaSサービスが提供するリモートMCPサーバーには、HTTPトランスポートで接続します。

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

OAuth認証が必要なサーバーの場合は、/mcp コマンドからブラウザ認証を行います。

まとめ

  • MCPはClaude Codeと外部サービスをつなぐプロトコル。接続するとClaude Codeの対話内から外部ツールを直接操作できる
  • claude mcp add コマンドまたは .mcp.json ファイルでMCPサーバーを設定する
  • 設定後は claude mcp list や /mcp で接続状態を確認する
  • APIキーは環境変数で渡し、信頼できるサーバーのみを利用する