MCP サーバー — 外部ツールをClaude Code / Cursorに接続する

**Model Context Protocol（MCP）**は外部ツールとデータをAIエージェントに公開するための標準だ。Anthropicがオープン仕様として公開し、Claude Code、Cursor、Continue、その他が採用 — 同じインターフェースを共有している。

平たく言えば: 「毎回カスタム API ラッパーを書かずに、GPT や Claude が自分のファイルシステム / DB / GitHub に直接触れるようにしたい。」

MCP サーバーの本質は接続数ではなく、判断の質にあると考える — 信頼できるローカル stdio サーバーに絞ることで、攻撃面を最小に保てるからだ。以前は「なるべく多くのツールを接続しよう」と考えていた。いまでは必要なものだけを、検証済みのものだけに限ることが正しい設計だとわかっている。

このガイドでは、コアコンセプト・よく使うサーバーのセットアップ・デバッグ・セキュリティを解説する。

TL;DR

1. MCP は stdio/SSE 上の JSON-RPC — 標準化されたRPCでツールを公開
2. 公式サーバー: filesystem、GitHub、Slack、Postgres、Puppeteerなど — @modelcontextprotocol/server-*
3. 1つのクライアント設定: Claude Codeは ~/.claude/settings.json、Cursorはそのセンター設定UI — 同じJSONスキーマ
4. セキュリティルール#1: 読み取り専用サーバーを優先; 書き込み可能な場合は明示的なホワイトリストディレクトリのみ

前提条件

• Node.js 20+（npx用）
• MCPに対応したクライアント — Claude CodeまたはCursor
• 公開するサービスのAPIトークン（GitHub PAT、Slackなど）

1. MCPの基本概念（30秒）

2. Claude CodeにMCPを追加する

2.1 設定ファイル

~/.claude/settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/projects",
        "/Users/me/notes"
      ]
    }
  }
}

• コマンド引数 = 公開するディレクトリ（allow-list）— それ以外にはアクセスできない。
• 絶対パス。~/ は展開されない。

2.2 Claude Codeを再起動する

# 前のセッションを終了後
claude

2.3 確認

Claude Code内:

What tools are available?

filesystem MCPの read_file、write_file、list_directoryが表示されれば成功だ。

3. CursorにMCPを追加する

Settings（⌘,）→ Features → MCP → Add Server。JSON:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

同じスキーマだ。Claude Code と設定を共有できます — ~/.claude/settings.json をコピー。

4. よく使う6つのサーバー

4.1 Filesystem

"filesystem": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
}

ファイルの読み取り/書き込み/検索。パスのホワイトリストを強制する。

4.2 GitHub

"github": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
  }
}

Issue、PR、コード検索。PAT のスコープは最小限（repo、read:user）にしてください。

4.3 Slack

"slack": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-slack"],
  "env": {
    "SLACK_BOT_TOKEN": "xoxb-...",
    "SLACK_TEAM_ID": "T..."
  }
}

チャンネルの読み取り/送信。ユーザートークンよりボットトークンを優先してください。

4.4 PostgreSQL（読み取り専用）

"postgres": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-postgres",
    "postgresql://readonly_user:pass@localhost/mydb"
  ]
}

読み取り専用ユーザーで接続する — AI は任意のクエリを実行できるので、権限を分けてください。

4.5 Puppeteer

"puppeteer": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
}

実際のブラウザ自動化。スクリーンショット、DOM操作、JS実行。

4.6 SQLite

"sqlite": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/db.sqlite"]
}

ローカルSQLiteの分析に最適。

5. 1Passwordでシークレットを管理する

トークンをJSONにプレーンテキストで書かないでください。multi-os/password-managerのパターンを使う:

オプションA — chezmoi テンプレート

~/.claude/settings.json をchezmoiに置いて {{ onepasswordRead "op://..." }} を使う。

オプションB — ラッパースクリプト

# ~/bin/mcp-github.sh
#!/bin/bash
export GITHUB_PERSONAL_ACCESS_TOKEN="$(op item get GitHub --fields token --reveal)"
exec npx -y @modelcontextprotocol/server-github

settings.json:

"github": {
  "command": "/Users/me/bin/mcp-github.sh"
}

op CLIはGUIの生体認証で自動解錠 — スムーズだ。

6. カスタムMCP サーバーを書く

独自ツールを公開するのに10分。Node.js 例（my-server.js）:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
const server = new Server(
  { name: "my-tools", version: "0.1.0" },
  { capabilities: { tools: {} } }
);
 
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "echo",
      description: "Echo back input",
      inputSchema: {
        type: "object",
        properties: { msg: { type: "string" } },
        required: ["msg"],
      },
    },
  ],
}));
 
server.setRequestHandler(CallToolRequestSchema, async (req) => {
  if (req.params.name === "echo") {
    return { content: [{ type: "text", text: req.params.arguments.msg }] };
  }
  throw new Error(`Unknown tool: ${req.params.name}`);
});
 
await server.connect(new StdioServerTransport());

"my-tools": {
  "command": "node",
  "args": ["/Users/me/code/my-server.js"]
}

MCP SDK 公式サンプルも参照してください。

7. デバッグ

ツールが表示されない

• クライアント（Claude Code/Cursor）を完全に再起動
• npx が実行可能か確認 — which npx / Node 20+
• サーバーのログ — Claude Codeの場合、システムログまたはstderrを確認

MCP Inspector

公式デバッグツール:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

直接RPC呼び出しができるブラウザUI — ツール定義とレスポンスを可視化する。

レスポンスが遅い

• 初回呼び出し: npx -y でパッケージをダウンロード — 一度だけ遅く、その後はキャッシュで速い
• 永続インストール: npm i -g @modelcontextprotocol/server-filesystem → command: "mcp-server-filesystem"

8. セキュリティ

フォルダの allow-list 化のみ

filesystem では、常に 明示的なパス引数を渡してください。省略するとホームディレクトリ全体が公開される。

読み取り専用 DB ユーザー

Postgres/SQLite では別の読み取り専用ユーザーを作成。AI が DROP TABLE できないようにする。

最小限のトークンスコープ

GitHub PAT: repo + read:user。admin:org は不要。

env 漏洩を防ぐ

settings.json をコミットしないでください。必要な場合は chezmoi/シークレット統合（§5）を使う。

ランダムな MCP サーバーを信頼しない

公式の @modelcontextprotocol/* または監査できる OSS にとどめてください。任意の npm パッケージにトークンを渡さないこと。

確認

1. settings.json編集後、Claude Codeを再起動 → 「利用可能なツールを表示して」→ 新しいサーバーのツールが表示される
2. 「ルートのファイルを見せて」（filesystemサーバーで）
3. 「最新5つのPRをまとめて」（GitHubサーバーで）
4. MCP InspectorでツールDefinitionを確認
5. ホワイトリスト外のパスを試みる → 拒否される

トラブルシューティング

npx -y でパッケージが見つからない

• @modelcontextprotocol/server-XXX のパッケージ名のタイポがよくある。公式リストを確認
• 企業の npm レジストリでは、npmrc でパブリックレジストリへのフォールバックを設定

Windowsでパスが壊れる

JSONで \ をエスケープするか / を使う:

"args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/Users/me/projects"]

Claude Codeが認識しない

• ~/.claude/settings.json の構文を検証 — jq . ~/.claude/settings.json
• 他のsettings.jsonの場所（~/.claude.json、プロジェクトの .claude/settings.json）との混同に注意

レスポンスで一部ツールが欠けている

非決定的なツールリスティングを持つサーバーは再起動で変わることがある。listToolsハンドラを決定論的にしてください。

トークンが誤ってコミットされた

すぐにローテーションしてください（GitHub → Personal access tokens → Revoke + 再発行）。git filter-repo でgit履歴を削除する。

参考リンク

• Claude Code セットアップ — hostセットアップ
• Cursor セットアップ — hostセットアップ
• マルチエージェントワークフロー — main/sub分割
• パスワードマネージャー — トークンセキュリティ
• Model Context Protocol（公式）
• 公式サーバープール

変更履歴

• 2026-05-12: 初版。コンセプト + クライアントセットアップ + 6サーバー + シークレット管理 + カスタムサーバー + デバッグ + セキュリティ + 5つのトラブルシューティング。