콘텐츠로 건너뛰기
DevLab

MCP 서버 보일러플레이트

Anthropic의 Model Context Protocol (MCP) Server를 tools / resources / prompts를 구조화된 형식으로 정의하기만 하면 TypeScript / Python 스켈레톤 코드로 변환합니다. Claude Desktop / Claude Code / Cursor의 MCP 클라이언트에서 바로 사용할 수 있는 형식 (stdio transport).

완전 무료 가입 불필요 브라우저 완결 즉시 다운로드 5 개 언어 다크 모드

⚠ MCP SDK 활발 업데이트. 생성 코드: TS SDK ^1.0 / Python SDK >=1.0 가정. 최신 사양은 modelcontextprotocol.io

Anthropic/OpenAI/Gemini 변환은: JSON Schema → Tool Use →

⚡ 프리셋

🔧 Tools (LLM 함수)

📚 Resources (리소스)

💬 Prompts (템플릿)

⬇ 

        

    


    

        
💡 셋업 절차

        
    
            
  1. "전체 zip"
    2. 
            
  2. 압축 해제 후 「의존성 설치」(npm install / pip install -r requirements.txt) 실행
    3. 
            
  3. ~/Library/Application Support/Claude/claude_desktop_config.json에 「Claude config」를 추가하기
    4. 
            
  4. Claude 재시작
    5. 
        

    






    
📖 자주 걸리는 지점


        
tools / resources / prompts 를 폼으로 정의하면 Model Context Protocol 서버의 뼈대를 TypeScript 또는 Python 으로 출력합니다 (stdio transport). Claude Desktop / Claude Code / Cursor 같은 MCP 클라이언트에 그대로 등록할 수 있는 형태입니다. 처리는 브라우저 안에서 끝납니다. 생성되는 것은 뼈대뿐이며 — 각 도구의 내용은 직접 써야 합니다. 그리고 MCP 에서 막히는 곳은 대개 코드 안이 아니라 「클라이언트와 서버의 경계」에 있습니다: 프로세스의 기동, 표준 입출력, 환경 변수. 아래가 그 셋입니다.

    
        

        

            
                

                    사례
                    무슨 일이 일어나는가
                    어떻게 하면 되는가
                

            
            
                                

                    표준 출력에 한 줄만 써도 깨진다
                    stdio transport 에서는 표준 출력 자체가 프로토콜의 통신로입니다 — JSON-RPC 메시지만 흐르는 것을 전제로 합니다. 따라서 console.log() 나 print() 를 한 번 쓴 것만으로 프레임 도중에 이물이 섞여 클라이언트 쪽 파서가 깨집니다. 까다로운 것은 오류 메시지가 완전히 엉뚱해진다는 점으로, 「서버가 접속할 수 없다」 「예기치 않은 토큰」 「끊겼습니다」 같은 원인을 가리키지 않는 표시가 됩니다. 그리고 자기가 쓴 console.log 만이 원인이라는 법도 없습니다 — 의존 라이브러리가 기동할 때 내는 경고, 패키지 매니저의 갱신 알림, 셸 초기화 스크립트의 출력도 모두 같은 경로로 흘러 들어옵니다.
                    로그는 전부 표준 에러 출력으로 내보내세요. TypeScript 라면 console.error(), Python 이라면 print(..., file=sys.stderr) 나 logging.basicConfig(stream=sys.stderr) 입니다 — 표준 에러는 프로토콜에 쓰이지 않으므로 아무리 써도 안전하고 게다가 클라이언트 쪽 로그에 남습니다. 팀으로 개발한다면 console.log 를 lint 로 금지하세요 (ESLint 의 no-console 에 allow: ['error', 'warn']) — 디버그 중에 무심코 써 놓고 지우는 것을 잊은 채 커밋되는 것이 가장 흔한 패턴입니다. 가려내는 절차도 익혀 두면 빠릅니다: 터미널에서 서버를 직접 기동해 표준 출력에 JSON 이외의 것이 나오지 않는지 눈으로 보세요 — 여기에 무언가 표시되면 그것이 그대로 원인입니다.
                

                                

                    description 이 사실상 프롬프트가 되어 있다
                    모델이 그 도구를 부를지 말지, 어떤 인자를 넘길지를 판단하는 재료는 도구 이름·description·각 파라미터의 설명뿐입니다 — 구현 코드는 전혀 보이지 않습니다. 따라서 「데이터를 가져옵니다」 같은 설명을 쓰면 언제 불러야 하는지를 판단할 수 없어 필요한 자리에서 불리지 않거나 관계없는 자리에서 불립니다. 또 하나의 실패가 도구의 개수로, 비슷한 이름의 도구를 스무 개 늘어놓으면 모델은 선택을 그르치기 쉬워집니다. 그리고 반환값도 설계 대상입니다 — 거대한 JSON 을 그대로 돌려주면 컨텍스트를 다 써 버린 데다 모델이 필요한 부분을 찾지 못합니다. MCP 서버의 품질은 코드보다 「말」로 정해집니다.
                    description 에는 「무엇을 하는가」가 아니라 「언제 쓰는가·언제 쓰지 않는가」를 쓰세요. 「사용자가 특정 주문의 배송 상황을 물었을 때 쓴다. 주문 ID 를 알고 있는 경우에만. 상품 검색에는 쓰지 않는다」처럼 경계를 명시할수록 선택의 정확도가 올라갑니다. 파라미터의 설명에는 형식의 예를 넣으세요 — 「ISO 8601 의 날짜 (예: 2025-03-04)」라고 쓰기만 해도 포맷 차이로 인한 실패가 거의 사라집니다. 도구는 적게, 이름은 서로 헷갈리지 않게: get_user 와 fetch_user 를 둘 다 두지 마세요. 반환값은 요약해서 돌려주고 상세가 필요할 때만 두 번째 호출로 가지러 가게 하는 설계로 하세요 — 페이징이나 limit 을 처음부터 넣어 두면 나중에 다시 만들지 않아도 됩니다.
                

                                

                    터미널에서는 되는데 클라이언트에서는 기동하지 않는다
                    MCP 클라이언트는 서버를 자식 프로세스로 기동합니다만 그 프로세스의 환경은 당신의 터미널과는 다른 것입니다. GUI 앱에서 기동된 경우 .bashrc 나 .zshrc 는 읽히지 않고 PATH 는 최소한이 됩니다. 결과적으로 nvm·pyenv·asdf·volta 같은 버전 관리 도구가 끼워 넣는 PATH 가 존재하지 않아 node 나 python 자체를 찾지 못합니다 — 오류는 spawn ENOENT 한 줄뿐입니다. 환경 변수도 마찬가지로 이어지지 않으므로 API 키를 export 해서 동작을 확인한 서버는 클라이언트에서 기동하면 인증에 실패합니다. 현재 디렉터리도 기대한 곳이 아닙니다 — 상대 경로로 읽고 있는 설정 파일은 찾을 수 없습니다.
                    클라이언트 설정에는 인터프리터의 절대 경로를 쓰세요. which node / which python3 의 결과를 그대로 command 에 넣습니다 — 버전 관리 도구를 쓰고 있다면 이것은 사실상 필수입니다. 환경 변수는 클라이언트 설정의 env 키로 명시적으로 넘깁니다 ("env": {"API_KEY": "..."} ) — 서버 쪽에서 .env 를 읽는 설계라면 그 경로도 절대 경로로 하세요. 파일을 읽을 때는 __dirname (TypeScript) 이나 Path(__file__).parent (Python) 를 기점으로 삼고 현재 디렉터리에 의존하지 마세요. 그리고 문제가 생기면 먼저 클라이언트의 로그를 여세요 — 표준 에러로 낸 로그가 거기에 모여 있으므로 원인은 대개 첫 줄에 적혀 있습니다.
                

                            
        

    

    
        
MCP 서버는 당신의 권한으로 동작하는 프로그램입니다. 파일을 읽고 쓰고 네트워크에 나가고 명령을 실행할 수 있습니다 — 그리고 그것을 부를지 말지를 정하는 것은 외부의 텍스트를 읽고 있는 모델입니다. 즉 「모델이 읽은 내용」이 간접적으로 도구 호출을 유도할 수 있다는 뜻입니다 (프롬프트 인젝션). 파괴적인 조작은 도구로 공개하지 마세요 — 삭제·발송·결제·배포처럼 되돌릴 수 없는 조작은 사람의 확인을 끼우는 설계로 하는 것이 원칙입니다. 읽기 전용 도구와 쓰기를 하는 도구를 서버째 나누는 것도 유효합니다. 구현 면에서는 경로 인자를 반드시 정규화해 허용된 디렉터리 안쪽에 들어가는지 검증하고 (../ 연타로 밖으로 나갈 수 없도록), 명령 실행은 배열 형식으로 인자를 넘깁니다. 마지막으로 MCP SDK 는 활발히 갱신되고 있습니다 — 생성 코드는 출발점이며 실제 API 는 modelcontextprotocol.io 의 최신판에서 확인하세요.

    









    
📖 사용법

    
    
                
  1. 
            1
            
    
                
    프리셋 / 자작
    
                
    프리셋 또는 수동
    
            
    
        
    2. 
                
  2. 
            2
            
    
                
    언어 / 설정
    
                
    TS / Python
    
            
    
        
    3. 
                
  3. 
            3
            
    
                
    zip 다운로드
    
                
    zip → install → config
    
            
    
        
    4. 
            






    
❓ 자주 묻는 질문

    

                

            
                MCP란?
                
            
            
Anthropic의 MCP

        

                

            
                stdio vs HTTP?
                
            
            
stdio = 로컬, HTTP = 원격

        

                

            
                구분?
                
            
            
Tools/Resources/Prompts

        

            







    

        
            🐛 이 도구에서 문제가 발생했나요?
            
        

        

            무료 · 가입 불필요. 재현 절차만이라도 도움이 됩니다. 보고는 운영자에게 직접 전달되어 개선에 사용됩니다.
        


        

                        

            

                
                
            


            

                
                
                

                    ※ 재현을 위해 브라우저 정보 (UA / 화면 / 언어 / URL) 가 자동 전송됩니다