나만의 MCP 서버 만들고 npm에 배포하기 (feat. velog-mcp)

최근 AI를 활용한 개발 워크플로우, 이른바 '바이브 코딩(Vibe Coding)'이 대세로 자리 잡았어요.

자연스럽게 AI 모델에게 내 프로젝트나 외부 서비스의 정확한 컨텍스트를 제공하는 일이 핵심 경쟁력이 되었죠.

이때 등장한 표준 규격이 바로 MCP(Model Context Protocol)입니다.

 

공식 API가 없는 서비스라도 브라우저가 할 수 있는 일이라면, 코드로 구현해 AI의 새로운 능력으로 확장할 수 있어요.

저는 이 방식을 응용해서 AI가 제 Velog 계정에 직접 접근해 글을 읽고 쓸 수 있는 velog-mcp를 개발하고 npm에 배포했습니다.

 

이번 글에서는 가장 기초적인 MCP 서버 구현부터 npm 오픈소스 배포, 그리고 실전 응용 인사이트까지 단계별로 알아볼게요.

 

💡 이 글에서 다룰 내용

• MCP 서버의 기본 구조와 통신 방식(stdio) 이해하기
• tsup을 활용해 빠르고 직관적인 TypeScript 빌드 환경 구성하기
• 완성한 패키지를 npm에 배포하고 CLI 환경에서 실행하기
• 공식 API가 없는 플랫폼을 AI와 연동하는 실무 아이디어 (velog-mcp 사례 중심)

 

MCP(Model Context Protocol)란?

---

예전에는 AI에게 내 로컬 파일이나 외부 서비스의 데이터를 알려주려면 텍스트를 일일이 복사해서 붙여넣어야 했어요.

MCP는 바로 이 과정을 자동화하기 위해 탄생한 'AI와 도구 사이의 표준 통신 규격'이에요.

 

클라이언트와 서버가 통신할 때 REST API나 GraphQL을 사용하는 것과 비슷해요.

AI(Claude, Cursor 등)가 우리의 로컬 환경이나 외부 서비스(Velog, GitHub 등)와 소통하기 위해 사용하는 API 표준이라고 생각하면 이해하기 쉬워요.

 

우리가 MCP 서버를 만들어 도구(Tool)를 등록해 두면, AI는 필요할 때마다 이 서버에 "이 도구를 실행해서 결과를 알려줘"라고 요청하게 됩니다.

 

나만의 첫 MCP 서버 구현하기

---

프로젝트 초기화 및 SDK 설치

먼저 새로운 디렉토리를 만들고 프로젝트를 초기화해 주세요.

그다음, MCP 서버 구현에 필요한 공식 SDK와 파라미터 검증을 위한 zod를 설치합니다.

mkdir my-first-mcp
cd my-first-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod

 

기본 서버 로직 작성

프로젝트 루트에 src 폴더를 만들고 index.ts 파일을 생성해요.

@modelcontextprotocol/sdk가 제공하는 McpServer 클래스를 사용하면 복잡한 설정 없이도 AI가 사용할 도구(Tool)를 쉽게 등록할 수 있어요.

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// 1. 서버 인스턴스 생성
const server = new McpServer({
	name: "my-first-mcp-server",
	version: "1.0.0"
});

// 2. AI가 사용할 수 있는 도구(Tool) 등록
server.tool("say_hello",
	{ name: z.string() },
	async ({ name }) => {
		return {
			content: [{ type: "text", text: Hello, ${name}! This is my first MCP. }]
		};
	}
);

// 3. 서버 실행 (표준 입출력 방식 사용)
async function run() {
	const transport = new StdioServerTransport();
	await server.connect(transport);
	console.error("MCP Server is running on stdio");
}

run().catch(console.error);

 

로그를 남길 때는 반드시 console.error를 사용해 주세요!

 

MCP는 주로 표준 입출력(stdio)을 통해 AI 클라이언트(Claude Desktop, Cursor 등)와 통신해요.

이때 습관처럼 console.log를 사용하면 JSON 형식의 통신 포맷이 깨져버립니다.

따라서 서버 상태나 디버깅 로그를 출력할 때는 꼭 console.error를 사용해야 정상적으로 동작해요.

 

번들링 및 npm 배포 준비

---

TypeScript 코드를 CLI에서 바로 실행할 수 있는 JavaScript로 변환해 볼게요.

설정이 직관적이고 빌드 속도가 빠른 esbuild 기반의 tsup을 사용할 거예요.

 

빌드 도구 설치 및 tsup 설정

npm install -D tsup typescript @types/node

 

프로젝트 루트에 tsup.config.ts 파일을 생성해 주세요.

이 프로젝트는 CLI 도구로 동작해야 하므로, 빌드 결과물 최상단에 #!/usr/bin/env node (Shebang)를 자동으로 주입하도록 설정하는 것이 핵심이에요.

// tsup.config.ts
import { defineConfig } from "tsup";

export default defineConfig({
	entry: ["src/index.ts"],
	format: ["esm"],
	dts: true,
	clean: true,
	minify: true,
	banner: {
		js: "#!/usr/bin/env node", // CLI 실행을 위한 Shebang 필수 추가
	},
});

 

package.json 마무리 설정

다른 개발자들이 npx 명령어로 쉽게 실행할 수 있도록 package.json을 다듬어 줄 차례예요.

여기서 bin 필드를 설정하는 것이 가장 중요합니다.

{
  "name": "my-first-mcp",
  "version": "1.0.0",
  "description": "My awesome MCP server",
  "main": "dist/index.js",
  "type": "module",
  "bin": {
    "my-first-mcp": "./dist/index.js"
  },
  "scripts": {
    "build": "tsup",
    "start": "node dist/index.js"
  },
  "files": [
    "dist"
  ]
}

 

이제 터미널에서 npm run build 명령어를 실행해 보세요.

dist 폴더에 배포 준비를 완벽하게 마친 실행 파일이 만들어질 거예요.

 

npm에 내 MCP 서버 배포하기

---

모든 준비를 마쳤다면 터미널에서 npm에 로그인한 후 패키지를 배포(publish)해 줄 차례예요.

배포하기 전에 package.json의 name 필드를 본인만의 고유한 패키지 이름으로 꼭 변경해 주세요!

npm login
npm publish

 

성공적으로 배포가 완료되었다면, 이제 전 세계 누구나 아래 명령어 한 줄로 여러분이 만든 MCP 서버를 실행하고 자신의 AI 클라이언트에 연결할 수 있어요.

npx 내가-지은-패키지-이름

 

실전 응용: 공식 API 없는 플랫폼 정복하기 (velog-mcp)

---

앞서 만든 기본 구조에 기술적 상상력을 조금만 더하면, 상상하는 대부분의 기능을 AI에게 쥐여줄 수 있어요.

제가 직접 개발한 velog-mcp가 아주 좋은 예시입니다.

 

이 프로젝트는 공식 API가 없는 기술 블로그 플랫폼인 Velog를 AI가 직접 제어할 수 있도록 만든 MCP 서버예요.

단순히 도구를 등록하는 수준을 넘어, 개발 과정에서 마주친 실무적인 난관들을 이렇게 해결했어요.

• 비공식 API 한계 극복: 브라우저의 네트워크 탭을 분석해 Velog의 비공식 GraphQL API를 찾아냈어요. 이를 바탕으로 글 읽기, 쓰기, 트렌딩 조회 도구(Tool)를 구성했습니다.
• 로그인(인증) 문제 우회: OAuth나 API Key가 제공되지 않는 환경을 극복하기 위해, 사용자의 로컬 OS(macOS, Windows, Linux)에 저장된 Chrome 쿠키 SQLite DB를 직접 읽고 복호화했어요. 이 방식으로 인증 세션을 자연스럽게 가져올 수 있었죠.

이런 접근 방식 덕분에 복잡하게 토큰을 복사해서 붙여넣을 필요가 없어졌어요.

아래 명령어 한 줄이면 Claude나 Cursor가 내 Velog 계정에 곧바로 접근할 수 있답니다.

claude mcp add velog -- npx -y velog-mcp

 

이제 AI에게 오늘 공부한 내용으로 TIL 작성해서 비공개로 올려줘라고 명령하면 척척 수행해 내요.

방금 우리가 함께 만든 간단한 say_hello 도구에서 출발해 여기까지 확장할 수 있는 것이죠.

 

더 복잡한 구현 코드나 쿠키 복호화 로직 등, 실전 기술이 궁금하시다면 velog-mcp 깃허브 저장소를 참고해 주세요.

여러분도 나만의 멋진 MCP를 직접 만들어 보시기를 강력히 추천합니다!