Todo List MCP Server

Python으로 작성된 간단하고 초보자 친화적인 Model Context Protocol (MCP) 서버입니다. 모든 MCP 호환 AI 클라이언트(예: Claude Desktop)가 컴퓨터의 할 일 목록을 다섯 가지 도구(추가, 보기, ID로 조회, 완료, 삭제)로 관리할 수 있게 해 줍니다.

공식 MCP Python SDK (mcp[cli])와 고수준 FastMCP 인터페이스로 구축되었습니다. 데이터는 별도 데이터베이스 없이 일반 JSON 파일에 로컬로 저장됩니다.

1. 이 프로젝트가 하는 일

이 MCP 서버는 연결된 모든 AI 클라이언트에 5가지 도구를 제공합니다:

모든 데이터는 todos.json에 저장되며, 첫 할 일을 추가할 때 자동으로 생성됩니다.

Related MCP server: Task MCP Server

2. 프로젝트 구조

todo-mcp-server/
├── server.py          # Main MCP server — defines the 5 tools
├── storage.py          # Handles reading/writing todos.json
├── todos.json           # Auto-created data file (not committed to git)
├── requirements.txt     # Python dependencies     
├── .gitignore            # Files Git should ignore
└── README.md             

3. 설정

사전 요구 사항

• Python 3.10 이상

• pip (Python에 포함)

단계

# 1. Clone or download this project, then move into it
cd todo-mcp-server

# 2. Create a virtual environment
python -m venv venv

# 3. Activate it
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

4. 서버 실행

옵션 A — MCP Inspector (테스트에 권장):

mcp dev server.py

브라우저 기반 UI가 열리며, 각 도구를 수동으로 호출하고 JSON 응답을 확인할 수 있습니다.

옵션 B — Claude Desktop에 설치:

mcp install server.py --name "Todo List MCP Server"

이렇게 하면 서버가 등록되어 Claude Desktop이 자동으로 시작합니다.

옵션 C — 직접 실행:

python server.py

5. 테스트 / 예시 프롬프트 (Claude Desktop에서)

Claude Desktop에 연결한 후 다음을 시도해 보세요:

• "할 일 추가: 장보기, 설명: 우유, 계란, 빵"

• "내 모든 할 일 보여줘"

• "ID 1의 할 일 가져와"

• "할 일 1을 완료로 표시해"

• "할 일 2 삭제해"

6. 아키텍처

 MCP Client (Claude Desktop)
          │  (stdio / JSON-RPC)
          ▼
     server.py  (FastMCP tools)
          │
          ▼
     storage.py (reads/writes JSON)
          │
          ▼
     todos.json  (local data file)

클라이언트는 JSON 파일을 직접 건드리지 않습니다 — 도구만 호출하며, 서버가 데이터 저장 방식을 결정합니다. 이 분리는 MCP 설계의 핵심 아이디어입니다: 클라이언트는 도구가 내부적으로 어떻게 작동하는지 알 필요 없이, 무엇을 하는지만 알면 됩니다.

7. 학습 성과

이 프로젝트를 통해 배운 것:

• Model Context Protocol (MCP)이 무엇인지, LLM을 위한 도구 접근을 어떻게 표준화하는지

• MCP 서버, 클라이언트, 도구/리소스/프롬프트의 차이점

• 공식 Python SDK의 FastMCP 인터페이스를 사용하여 일반 Python 함수와 타입 힌트로 도구를 빠르게 구축하는 방법

• JSON 파일로 데이터를 로컬에 저장하고 관리하는 방법

• Claude Desktop에서 사용자 정의 MCP 서버를 연결하고 테스트하는 방법

• 작은 Python 프로젝트를 GitHub에 패키징, 문서화, 게시하는 방법

• Smithery 같은 마켓플레이스에 MCP 서버를 게시하는 기본 사항

라이선스

MIT — 자유롭게 사용, 수정, 공유할 수 있습니다.

작성자

Haseeba Yasin

이 프로젝트가 도움이 되었다면 저장소에 ⭐를 눌러 주세요.