🚀첫 번째 MCP 서버 구축: 완전 가이드

Source: Dev.to

소개

Model Context Protocol (MCP)은 AI 애플리케이션이 외부 도구 및 데이터 소스와 상호 작용하는 방식을 혁신하고 있습니다. Claude 통합, VSCode 확장 또는 맞춤형 AI 워크플로를 구축하든, MCP 서버를 이해하는 것은 현대 AI 개발에 필수적입니다.

이 가이드에서는 처음부터 완전한 기능을 갖춘 MCP 서버를 구축하고, 클라우드에 배포한 뒤, 인기 있는 MCP 클라이언트와 연결하는 방법을 다룹니다. 최종적으로 모든 MCP 클라이언트가 사용할 수 있는 날씨 정보 서버를 만들게 됩니다.

MCP (Model Context Protocol)는 AI 애플리케이션이 외부 데이터 소스와 도구에 연결하는 방식을 표준화하는 오픈 프로토콜입니다. 이를 데이터베이스, API, 파일 시스템, 비즈니스 도구 등에 안전하게 접근할 수 있게 해주는 범용 어댑터라고 생각하면 됩니다.

• 표준화된 통합: 하나의 프로토콜로 모든 MCP 호환 클라이언트에서 동작
• 보안 우선: 내장된 인증 및 권한 제어
• 유연한 아키텍처: 로컬 및 원격 서버 지원
• 도구 탐색: 클라이언트가 사용 가능한 기능을 자동으로 발견

MCP 서버는 세 가지 주요 구성 요소로 이루어집니다:

1. Resources – 서버가 제공할 수 있는 데이터 소스(파일, 데이터베이스 레코드, API 데이터)
2. Tools – 서버가 수행할 수 있는 작업(생성, 업데이트, 삭제 등)
3. Prompts – 일반 작업을 위한 사전 정의된 템플릿

아래에서는 공개 API를 활용해 날씨 정보를 제공하는 실용적인 MCP 서버를 구축합니다.

프로젝트 설정

mkdir weather-mcp-server
cd weather-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk axios dotenv
npm install -D @types/node typescript

프로젝트 구조

weather-mcp-server/
├── src/
│   ├── index.ts
│   ├── server.ts
│   └── weatherService.ts
├── package.json
├── tsconfig.json
└── .env

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

package.json (스크립트)

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsc && node dist/index.js"
  },
  "type": "module"
}

날씨 서비스 (src/weatherService.ts)

import axios from 'axios';

export interface WeatherData {
  location: string;
  temperature: number;
  condition: string;
  humidity: number;
  windSpeed: number;
  description: string;
}

export class WeatherService {
  private apiKey: string;
  private baseUrl = 'https://api.openweathermap.org/data/2.5';

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async getCurrentWeather(city: string): Promise {
    try {
      const response = await axios.get(`${this.baseUrl}/weather`, {
        params: {
          q: city,
          appid: this.apiKey,
          units: 'metric'
        }
      });

      const data = response.data;

      return {
        location: `${data.name}, ${data.sys.country}`,
        temperature: Math.round(data.main.temp),
        condition: data.weather[0].main,
        humidity: data.main.humidity,
        windSpeed: data.wind.speed,
        description: data.weather[0].description
      };
    } catch (error) {
      throw new Error(`Failed to fetch weather data: ${error}`);
    }
  }

  async getForecast(city: string, days: number = 5): Promise {
    try {
      const response = await axios.get(`${this.baseUrl}/forecast`, {
        params: {
          q: city,
          appid: this.apiKey,
          units: 'metric',
          cnt: days * 8 // API returns 3‑hour intervals
        }
      });

      return response.data;
    } catch (error) {
      throw new Error(`Failed to fetch forecast data: ${error}`);
    }
  }
}

MCP 서버 (src/server.ts)

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  ListResourcesRequestSchema,
  ReadResourceRequestSchema
} from '@modelcontextprotocol/sdk/types.js';
import { WeatherService } from './weatherService.js';

export class WeatherMCPServer {
  private server: Server;
  private weatherService: WeatherService;

  constructor(apiKey: string) {
    this.weatherService = new WeatherService(apiKey);
    this.server = new Server(
      {
        name: 'weather-mcp-server',
        version: '1.0.0',
      },
      {
        capabilities: {
          tools: {},
          resources: {}
        },
      }
    );

    this.setupHandlers();
  }

  private setupHandlers() {
    // List available tools
    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools: [
        {
          name: 'get_current_weather',
          description: 'Get current weather information for a city',
          inputSchema: {
            type: 'object',
            properties: {
              city: {
                type: 'string',
                description: 'City name (e.g., "London", "New York")'
              }
            },
            required: ['city']
          }
        },
        {
          name: 'get_forecast',
          description: 'Get weather forecast for upcoming days',
          inputSchema: {
            type: 'object',
            properties: {
              city: {
                type: 'string',
                description: 'City name'
              },
              days: {
                type: 'number',
                description: 'Number of days (1-5)',
                default: 5
              }
            },
            required: ['city']
          }
        }
      ]
    }));

    // Handle tool calls
    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;

      try {
        if (name === 'get_current_weather') {
          const weather = await this.weatherService.getCurrentWeather(
            args.city as string
          );

          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(weather, null, 2)
              }
            ]
          };
        }

        if (name === 'get_forecast') {
          const forecast = await this.weatherService.getForecast(
            args.city as string,
            (args.days as number) || 5
          );

          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify(forecast, null, 2)
              }
            ]
          };
        }

        throw new Error(`Unknown tool: ${name}`);
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: `Error: ${error}`
            }
          ],
          isError: true
        };
      }
    });

    // List available resources
    this.server.setRequestHandler(ListResourcesRequestSchema, async () => ({
      resources: [
        {
          uri: 'weather://cities',
          name: 'Popular Cities',
          description: 'List of popular cities for weather queries',
          mimeType: 'application/json'
        }
      ]
    }));

    // Read resources
    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
      const { uri } = request.params;

      if (uri === 'weather://cities') {
        const cities = [
          'London', 'New York', 'Tokyo', 'Paris', 'Sydney',
          'Berlin', 'Toronto', 'Singapore', 'Dubai', 'Mumbai'
        ];

        return {
          contents: [
            {
              type: 'application/json',
              data: JSON.stringify(cities, null, 2)
            }
          ]
        };
      }

      // Fallback for unknown resources
      return {
        contents: [],
        isError: true,
        errorMessage: `Resource not found: ${uri}`
      };
    });
  }

  // Start the server (e.g., using stdio transport)
  public start() {
    const transport = new StdioServerTransport(this.server);
    transport.start();
  }
}

서버 실행

Create a .env file with your OpenWeatherMap API key:

OPENWEATHER_API_KEY=your_api_key_here

Then start the server:

npm run build
npm start

The server will listen on standard I/O, ready for any MCP‑compatible client (e.g., Claude) to discover the get_current_weather and get_forecast tools, as well as the weather://cities resource.