Todo List MCP Server

일반 JSON 파일을 MCP 호환 클라이언트(Claude Desktop, Claude Code, Cursor 등)가 대신 읽고 관리할 수 있는 할 일 목록으로 바꿔주는 작은 Model Context Protocol 서버입니다.

기능

다섯 가지 도구와 하나의 리소스를 제공합니다:

데이터는 server.py 옆의 todos.json에 저장되므로 재시작 후에도 유지됩니다.

Related MCP server: MCP Todo Server

설정

# 1. Clone / copy this folder
cd todo-mcp

# 2. Create a virtual environment and install dependencies
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 3. Run it directly to sanity-check it starts (Ctrl+C to stop)
python server.py

MCP 클라이언트에 연결하기

Claude Desktop

claude_desktop_config.json(설정 → 개발자 → 구성 편집)에 다음을 추가하세요:

{
  "mcpServers": {
    "todo-list": {
      "command": "/absolute/path/to/todo-mcp/venv/bin/python",
      "args": ["/absolute/path/to/todo-mcp/server.py"]
    }
  }
}

Claude Desktop을 다시 시작하면 도구 선택기(망치 아이콘)에서 할 일 도구를 사용할 수 있습니다. 다음과 같이 시도해 보세요: "높은 우선순위 할 일로 'finish MCP ticket'을 추가한 다음, 대기 중인 모든 항목을 보여줘."

MCP Inspector(로컬 디버깅용)

npx @modelcontextprotocol/inspector python server.py

이렇게 하면 브라우저 UI가 열리며 각 도구를 수동으로 호출하고 원시 JSON-RPC 요청/응답을 볼 수 있습니다. 클라이언트와 서버 간에 실제로 오가는 데이터를 이해하는 가장 좋은 방법입니다.

Smithery에 배포하기

1. 이 폴더를 공개 GitHub 저장소에 푸시합니다(server.py, pyproject.toml, requirements.txt, smithery.yaml 필요).

2. smithery.ai → 새 서버 → GitHub 저장소를 연결합니다.

3. Smithery는 smithery.yaml을 읽고 서버 시작 방법(stdio를 통한 python server.py)을 파악한 후 자동으로 빌드/배포합니다.

4. 배포가 완료되면 누구나 Smithery 목록 페이지에서 바로 자신의 MCP 클라이언트에 추가할 수 있습니다. 사용자 측에서 별도의 로컬 설정이 필요 없습니다.

구축 방식에 대한 참고 사항

공식 MCP Python SDK와 FastMCP를 사용하여 구축되었습니다. FastMCP는 @mcp.tool() 데코레이터를 통해 일반 Python 함수를 MCP 도구로 변환합니다. 타입 힌트와 docstring은 자동으로 도구의 JSON 스키마와 설명이 되며, 클라이언트 모델이 이를 읽고 각 도구를 언제, 어떻게 호출할지 결정합니다.