Claude Code MCPサーバー完全ガイド — 自作手順から人気サーバーまで網羅

Model Context Protocol(MCP)はClaude Codeに外部システム連携を追加する公式プロトコルです。ファイルシステム / GitHub / Slack / Notion / DB等の任意のサービスに、Claudeが標準化された方法でアクセスできるようになります。

MCPの全体像、stdio / SSEの転送方式、最小実装、TypeScript / Python SDK、Claude Codeへの接続設定、人気MCPサーバー、よくあるつまずきまでを扱います。具体的なMCP実例カタログはMCPを実務で使うための導入ガイドとMCPサーバーの構築手順ガイドで扱っているので、本記事は「全体像 + 仕様 + 設計判断」に集中します。

Claude Code MCPとは

MCPはAnthropicが中心となって策定した「LLMとツール / データソースの間の標準プロトコル」です。「LLM用のUSB-C」と例えられることが多く、各サービスごとに独自統合を書くのではなく、共通の仕様で接続できる点が最大の特徴です。

主要な構成要素:

• MCPサーバー:外部システム(ファイルシステム、GitHub API、DB等)をMCPプロトコルで公開するプロセス
• MCPクライアント:Claude Code / Claude Desktop / 他のMCP対応アプリケーションが、サーバーを呼び出す側
• 転送方式:stdio(プロセス間通信)/ SSE(HTTPベース)の2種類
• 能力:Tools(関数呼び出し)/ Resources(参照可能なデータ)/ Prompts(プロンプトテンプレート)の3種

Claude CodeはMCPクライアントとして、settings.json で登録されたMCPサーバーを起動・呼び出します。Claude.ai Desktop / Cursor等の他のクライアントでも同じMCPサーバーを使い回せます。

stdio MCPとSSE MCPの使い分け

MCPには2つの転送方式があります。

選び方の原則:

1. ローカルPC内で完結する処理 → stdio:npx @modelcontextprotocol/server-filesystem のようにコマンドで起動、認証不要
2. クラウドサービスとの連携 → SSE:OAuth / APIキー認証が必要なケース。常駐サーバーがあれば複数クライアントで使い回せる
3. エンタープライズ統合 → SSE + OAuth:組織で集中管理したいMCPサーバーはSSEで立てて、認証情報は組織側で管理

実運用では「コマンドラインから即起動できるstdio」「リモート常駐のSSE」を用途で使い分けます。

最小実装(TypeScript SDK)

最小のMCPサーバーは数十行で書けます。TypeScript SDKの例:

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: "weather-mcp", version: "0.1.0" },
  { capabilities: { tools: {} } }
);
 
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_weather",
      description: "指定された都市の天気を返す",
      inputSchema: {
        type: "object",
        properties: { city: { type: "string" } },
        required: ["city"],
      },
    },
  ],
}));
 
server.setRequestHandler(CallToolRequestSchema, async (req) => {
  if (req.params.name === "get_weather") {
    const city = req.params.arguments?.city;
    return { content: [{ type: "text", text: `${city}: 晴れ、気温 20℃` }] };
  }
  throw new Error("Unknown tool");
});
 
const transport = new StdioServerTransport();
await server.connect(transport);

これを node dist/server.js で起動可能な状態にすればMCPサーバーとして成立します。Python SDKでも同等の構造で実装できます。

Python SDKの最小実装

from mcp.server import Server
from mcp.server.stdio import stdio_server
import mcp.types as types
 
app = Server("weather-mcp")
 
@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="get_weather",
            description="指定された都市の天気を返す",
            inputSchema={
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        )
    ]
 
@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    if name == "get_weather":
        city = arguments["city"]
        return [types.TextContent(type="text", text=f"{city}: 晴れ、気温 20℃")]
    raise ValueError(f"Unknown tool: {name}")
 
async def main():
    async with stdio_server() as (read, write):
        await app.run(read, write, app.create_initialization_options())
 
if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Pythonは pip install mcp でSDKを導入できます。

Claude Codeへの接続(settings.json)

実装したMCPサーバーは settings.json でClaude Codeに登録します。

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["./dist/weather-mcp/server.js"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
    }
  }
}

主要キーの意味:

設定ファイルの構造詳細はClaude Code設定ファイル完全ガイドを、Hooksとの関係はClaude Code Hooks完全ガイドを参照してください。

能力(Tools / Resources / Prompts)の使い分け

MCPサーバーは3種類の能力を公開できます。

ほとんどの実装はToolsのみで成立しますが、複雑なMCPではResourcesを併用してファイル / レコード一覧をClaudeに見せ、Toolsで個別操作を行う設計も使えます。

人気MCPサーバー一覧

Model Context Protocol公式リポジトリで多数の公式 / コミュニティ製MCPサーバーが提供されています。代表例:

詳細な人気MCPリストと評価は、MCPを実務で使うための導入ガイドで扱っています。

ネイティブTool useとMCPの使い分け

Claude CodeのBash / Edit / Read等のネイティブツールとMCPサーバーは似た機能を提供できますが、責務が異なります。

選び方:

1. Claude Codeが標準提供しているツール(Bash / Edit / Read等)で済むなら、それを使う
2. 外部サービス(GitHub / Slack / DB等)との統合はMCP
3. 複数クライアント(Claude.ai Desktop + Claude Code + Cursor等)で同じ統合を使い回すならMCP
4. OAuth / セッション状態が必要ならMCP

ネイティブツールとMCPの実務上の使い分けは、MCPを実務で使うための導入ガイドでも掘り下げています。

OAuthと認証フロー

クラウドサービスと連携するMCPサーバーはOAuth / APIキー認証が必要です。MCPプロトコルはOAuth 2.1のstep-up認証もサポートしており、初回起動時にブラウザでログイン → アクセストークン取得 → MCPサーバーがClaude Codeと通信する流れになります。

よくあるつまずきと回避策

MCPサーバー運用で踏みやすい落とし穴を7件集めました。

つまずき1:MCPサーバーが起動しない

settings.json の command / args のパスが間違っているケースが多いです。npx @modelcontextprotocol/server-filesystem /tmp をターミナルで手動実行して、エラーメッセージを確認するのが最初の一歩です。

つまずき2:認証情報が読み込まれない

env で渡した環境変数がMCPサーバー側で取得できないとき、子プロセスへの環境変数継承の問題か、シェル設定との競合が考えられます。env で明示的に必要な変数を渡し、デバッグ時は printenv でサーバープロセス内の環境を確認します。

つまずき3:stdioで大量データを返すとブロックする

stdio転送は同期的なので、巨大な応答(数MBのファイル内容等)を返すとClaude Code側のバッファでブロックします。リソース系の応答はチャンク化するか、SSE転送に切り替えるのが推奨です。

つまずき4:Tool nameの重複

複数のMCPサーバーが同じtool name(例: search)を公開すると、Claudeがどちらを呼ぶか曖昧になります。MCPの name プレフィックスで mcp_github_search のように一意化するか、各MCPのtool name設計で衝突を回避します。

つまずき5:権限の管理

MCPサーバーが付与された権限で「想定外の操作」を実行しないように、ネイティブのpermissionsとMCPのスコープを両側で絞ります。filesystem MCPなら起動時引数で許可するディレクトリを限定、github MCPならGitHub Personal Access Tokenのスコープを最小化、といった対策が必要です。

つまずき6:長時間タスクのタイムアウト

MCPサーバーへの呼び出しはデフォルトで30秒程度のタイムアウトがあります。長時間処理(大量ファイル走査、複雑なDBクエリ)は非同期化するか、ジョブを分割します。

つまずき7:他のクライアントで動かない

Claude Code用に書いたMCPサーバーがClaude.ai Desktopで動かない場合、転送方式(stdio vs SSE)の対応の違いか、設定ファイルパスの違いが原因です。Claude Desktop側のセットアップはDesktop Extensions(.dxt)でMCPサーバーを追加する方法で確認してください。

まとめ

Claude Code MCPは「Claudeにツール / データソースを標準仕様で追加するレイヤー」です。設計判断の軸は次の3つです。

1. ネイティブTool useで済むならMCPを作らない
2. 外部サービス連携 / 複数クライアント共有 / OAuth必要 → MCP
3. ローカル限定 → stdio、リモート / 認証 → SSE

具体的な実装はMCPサーバーの構築手順ガイドで扱い、人気サーバーの選び方やネイティブとの使い分けはMCPを実務で使うための導入ガイドで深掘りしています。

MCPは仕様が成熟途上ですが、Anthropic / OpenAI双方を含む業界標準として急速に普及しています。最初は公式MCP(filesystem / github / postgres)を使うところから始め、慣れたら自前MCPの実装に展開する形が現実的です。