계산기 MCP 서버

네 가지 도구(add, subtract, multiply, divide)를 제공하는 최소한의 MCP 서버로, 두 가지 버전이 있습니다:

• calculator_server.py — Python mcp SDK(FastMCP)로 구축되었습니다. @mcp.tool() 데코레이터가 타입 힌트/독스트링에서 JSON 스키마를 자동으로 생성하고 JSON-RPC 프로토콜을 처리해 줍니다.

• calculator_server_raw.py — 표준 라이브러리(json + sys)만 사용하여 처음부터 구현한 동일한 서버로, mcp 의존성이 없습니다. JSON-RPC 2.0 메시지 처리를 직접 구현하여 FastMCP가 내부적으로 수행하는 작업을 보여줍니다: stdin에서 줄바꿈으로 구분된 JSON 요청을 읽고, method(initialize, tools/list, tools/call, ping)에 따라 디스패치한 후, stdout에 JSON-RPC 응답을 씁니다. 프레이밍 세부 사항(LSF 스타일 헤더 없이 줄마다 JSON 객체 하나)은 파일 상단의 독스트링을 참조하세요.

설정

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt

Related MCP server: Math MCP Server

직접 실행하기 (stdio)

MCP 서버는 일반 CLI가 아니라 stdio(또는 HTTP)를 통해 통신합니다. "실행해서 출력을 보는" 방식이 아니라, 클라이언트가 연결하는 방식입니다. 두 가지 방법으로 시도할 수 있습니다:

1. MCP Inspector(시각적, 대화형) — Node.js/npx 필요:

.venv\Scripts\mcp dev calculator_server.py

브라우저 UI가 열리며 add, multiply 등을 직접 호출할 수 있습니다.

페이지가 로드되었지만 "Connect to an MCP server to start inspecting"이라고 표시되고 Tools 탭이 없다면, 사이드바가 명령을 자동으로 인식하지 못한 것입니다(이전/캐시된 세션 구성이 남아 있을 때 발생할 수 있음). 사이드바를 수동으로 채우고 Connect를 클릭하세요:

• Transport Type: STDIO

• Command: C:\Users\simon\mcpserversample\.venv\Scripts\python.exe

• Arguments: C:\Users\simon\mcpserversample\calculator_server.py

연결되면 상단 탐색에 Tools 탭이 나타나며, "List Tools"를 클릭하고 각 도구를 실행할 수 있습니다.

2. test_client.py — 이 저장소에 포함된 스크립트형 클라이언트로, 연결하고 도구를 나열한 다음 각각을 호출합니다. 기본값은 calculator_server.py이며, 다른 버전을 테스트하려면 경로를 전달하세요:

.venv\Scripts\python test_client.py
.venv\Scripts\python test_client.py calculator_server_raw.py

Claude Desktop에 연결하기

claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "calculator": {
      "command": "C:\\Users\\simon\\mcpserversample\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\simon\\mcpserversample\\calculator_server.py"]
    }
  }
}

작동 방식

• calculator_server.py는 FastMCP 서버를 생성하고 @mcp.tool() 데코레이터를 통해 각 Python 함수를 도구로 등록합니다. 함수의 타입 힌트와 독스트링이 도구의 JSON 스키마와 설명이 되며, 이는 호출 클라이언트(Claude, Inspector, 또는 test_client.py)가 보는 내용입니다.

• mcp.run()은 MCP stdio 전송을 사용하여 stdin/stdout에서 수신 대기하는 서버를 시작합니다. 이는 클라이언트가 로컬 MCP 서버를 하위 프로세스로 실행하고 통신하는 표준 방식입니다.

• 클라이언트는 연결한 후 list_tools()를 호출하여 사용 가능한 도구를 확인하고, call_tool(name, args)를 호출하여 하나를 실행하고 결과를 받습니다.