처음 MCP 서버를 만드는 방법

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

앱 개발

대상자

- TypeScript/JavaScript 기초 지식을 가진 개발자

- AI 에이전트와 실시간 데이터를 연결하고자 하는 프론트엔드/백엔드 개발자

- VS Code 및 GitHub Copilot 사용자

- 난이도: 초보자 수준 (Node.js 설치, npm 사용 기초 지식 필요)

핵심 요약

• MCP 서버 구축 방법: TypeScript SDK를 사용해 McpServer 클래스를 생성하고 get-weather 도구를 정의 (@modelcontextprotocol/sdk 라이브러리 사용)
• 실시간 데이터 연동: Open-Meteo API와 연동해 도시명 → 위도/경도 → 실시간 날씨 정보를 제공하는 2단계 프로세스 구현
• VS Code 연동: MCP: Add Server 명령어로 .vscode/mcp.json 파일 생성 후 GitHub Copilot과 연동하여 날씨 정보 요청 가능

섹션별 세부 요약

1. MCP 서버 개요 및 문제 정의

• MCP 서버는 AI 에이전트(예: GitHub Copilot)와 외부 도구/데이터 소스를 연결하는 중간 브리지 역할
• 문제점: GitHub Copilot이 VS Code에서 실시간 날씨 데이터를 제공하지 못함
• 해결책: MCP 서버를 통해 AI 에이전트가 실시간 날씨 API에 접근 가능

2. 개발 환경 설정

• 프로젝트 생성: mkdir mcp-weather-server 및 npm init -y 명령어 실행
• TypeScript 사용: package.json 파일에 "type": "module" 추가
• 필요한 라이브러리 설치:

```bash

npm install @modelcontextprotocol/sdk zod

```

• 의존성 확인: "@modelcontextprotocol/sdk": "^1.13.1", "zod": "^3.25.67"

3. MCP 서버 구현

• main.ts 파일 작성:

```typescript

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

import { z } from "zod";

```

• get-weather 도구 정의:

```typescript

server.tool('get-weather', 'Tool to get the weather of a city', { city: z.string() }, async ({ city }) => { ... });

```

• StdioServerTransport 사용: 터미널의 stdin/stdout을 통한 로컬 개발용 통신

4. 테스트 및 디버깅

• MCP Inspector 사용:

```bash

npx -y @modelcontextprotocol/inspector npx -y tsx main.ts

```

• 테스트 시나리오:

1. "Connect" 버튼 클릭 → 2. "Tools" 탭 선택 → 3. get-weather 도구 실행 → 4. 도시명 입력 후 "Run Tool" 클릭

• 예상 결과: "The weather in Palma de Mallorca is sunny"

5. Open-Meteo API 연동

• 단계 1: 도시명 → 위도/경도 변환 (Geocoding API 사용)
• 단계 2: 위도/경도 → 날씨 데이터 요청 (Weather API 사용)
• 예시 코드:

```typescript

const geoResponse = await fetch(https://geocoding-api.example.com?city=${city});

const weatherResponse = await fetch(https://weather-api.example.com?lat=${latitude}&lon=${longitude});

```

6. VS Code 연동

• VS Code에서 MCP 서버 추가:

1. 명령 팔레트(Cmd/Ctrl + Shift + P) → MCP: Add Server 입력
2. "Local server using stdio" 선택 → npx -y tsx main.ts 명령어 입력

• .vscode/mcp.json 파일 생성 예시:

```json

{"servers": {"my-weather-server": {"type": "stdio", "command": "npx", "args": ["-y", "tsx", "/Users/your-username/path/to/main.ts"]}}}

```

결론

• MCP 서버를 구축하려면 @modelcontextprotocol/sdk와 zod 라이브러리 사용
• Open-Meteo API는 API 키 없이 사용 가능하며, 도시명 → 위도/경도 → 날씨 데이터 2단계 연동 필수
• VS Code에서 MCP: Add Server 명령어로 GitHub Copilot과 연동하여 실시간 날씨 정보 요청 가능 (예: "What's the weather like in Tokyo?" 질문 시 JSON 데이터 반환)