mcp-task-manager

Anthropic의 Model Context Protocol을 통해 Claude Desktop에 연결되는 로컬 작업 관리자입니다. UI도, 백엔드 서비스도 필요 없습니다. 오직 Python 프로세스와 SQLite 파일만 있으면 됩니다. Claude와 대화하며 작업을 관리하세요.

"인증 버그를 수정하기 위한 우선순위가 높은 작업을 생성해줘. 마감일은 금요일이고, 태그는 backend로 해줘." → 작업 생성됨. "오늘 무엇에 집중해야 할까?" → 연체된 작업 + 긴급 작업 + 우선순위가 높은 작업을 반환합니다. "3번 작업을 완료로 표시하고 요약을 보여줘." → 완료 처리 + 통계.

스택: Python 3.11+ · FastMCP · SQLite · Pydantic v2 상태: 로컬에서 작동 중, 9개 도구 구현 완료

이 프로젝트의 목적

서버 수명 주기, 도구 등록, stdio 전송, 그리고 Claude가 자연어 요청에서 도구를 선택하는 방식을 포함하여 MCP를 처음부터 끝까지 학습하기 위해 구축되었습니다. 작지만 완벽한 예제이며, 직장에서 실제 내부 도구로 확장할 수 있는 유형의 프로젝트입니다.

작동 방식

MCP 서버는 로컬 하위 프로세스로 실행됩니다. Claude Desktop은 JSON-RPC를 사용하여 stdio를 통해 서버와 통신합니다. 메시지를 입력하면 Claude는 다음을 수행합니다:

1. 요청에 적합한 등록된 도구를 선택합니다.

2. 자연어에서 매개변수를 채웁니다.

3. 도구를 호출하고 구조화된 데이터(Pydantic 모델)를 반환받습니다.

4. 결과를 평이한 영어(또는 한국어)로 요약하여 알려줍니다.

Claude Desktop  ──── JSON-RPC (stdio) ────  server.py  (FastMCP)
                                                │
                                         TaskRepository
                                                │
                                           tasks.db  (SQLite)

도구

우선순위: low(낮음) · medium(중간) · high(높음) · urgent(긴급) 상태: pending(대기 중) · in_progress(진행 중) · completed(완료) · cancelled(취소됨)

프로젝트 구조

mcp-task-manager/
├── server.py           # FastMCP entry point, tool registration, lifespan
├── core/
│   ├── models.py       # Pydantic models + enums (Task, TaskCreate, TaskUpdate, TaskSummary)
│   └── repository.py   # SQLite DAO — CRUD, search, summary
├── tools/
│   └── __init__.py     # 9 MCP tool functions (thin layer over repository)
├── pyproject.toml
└── .env.example

세 개의 계층, 각각 하나의 책임:

• tools/ — MCP 대면 인터페이스. 각 함수에는 Claude가 호출 시점과 방법을 이해할 수 있도록 하는 독스트링이 포함되어 있습니다.

• core/repository.py — SQLite 액세스. 원시 SQL, status, priority, due_date에 인덱싱됨.

• core/models.py — 유효성 검사, 직렬화, 열거형(Enum).

설정

요구 사항: Python 3.11+, Claude Desktop.

git clone https://github.com/soltyDude/mcp-task-manager.git
cd mcp-task-manager

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -e .
cp .env.example .env

Claude Desktop에 연결

Claude Desktop 설정을 엽니다:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

서버를 추가합니다:

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

Claude Desktop을 다시 시작합니다. 🔌 아이콘 아래에 도구가 나타납니다.

구성

.env는 두 가지 변수를 지원합니다:

DATABASE_PATH=tasks.db       # where SQLite stores data
SERVER_NAME=mcp-task-manager # name shown in Claude Desktop

예시 세션

You:    Add a task: refactor the auth filter, high priority, due tomorrow, tags: backend, security

Claude: Created task #1 — "Refactor the auth filter" (high, due 2025-04-19, tags: backend, security)

You:    What's my plan for today?

Claude: 📅 Day plan for 2025-04-18
        🔥 FOCUS (urgent + high priority)
          [1] [HIGH] Refactor the auth filter  #backend #security
        📊 Total: 1 | In progress: 0 | Overdue: 0

You:    Mark it in progress and show a summary

Claude: Task #1 updated — status: in_progress.
        📊 Total: 1 | Pending: 0 | In progress: 1 | Completed: 0 | Overdue: 0

설계 노트

검토자로서 이 글을 읽는 경우를 대비해 몇 가지 선택 사항을 언급합니다:

• 수명 주기 범위의 저장소. TaskRepository는 FastMCP의 lifespan 컨텍스트 관리자에서 한 번 생성되고 ctx.request_context.lifespan_context를 통해 주입됩니다. 도구는 상태를 유지하지 않으며, 연결 세부 정보가 도구 코드로 유출되지 않습니다.

• 매직 스트링 대신 열거형 사용. Priority와 TaskStatus는 str 열거형으로, 입력 시 Pydantic에 의해 검증되고, SQLite에 문자열로 저장되며, 그 사이의 모든 곳에서 타입이 지정됩니다.

• TEXT 컬럼에 JSON으로 태그 저장. 로컬 도구의 경우 조인 테이블이 필요 없으므로 SQLite에 실용적입니다. 검색은 직렬화된 JSON에 대해 LIKE를 사용합니다. 나중에 Postgres로 이전하게 되면 text[]나 실제 태그 테이블이 될 것입니다.

• 핫 경로 인덱싱. status, priority, due_date — 모든 필터가 거치는 세 개의 컬럼입니다.

• plan_day 중복 제거. 긴급 및 우선순위가 높은 쿼리는 연체 목록과 겹칠 수 있으므로, 최종 집중 목록은 seen 세트를 사용하여 구축됩니다.

제한 사항 / 다음 단계

• 아직 테스트 없음 — 계획: 저장소 계층을 위한 인메모리 SQLite 픽스처를 포함한 pytest.

• 반복 작업 없음.

• 검색은 LIKE 기반임; 더 큰 데이터셋의 경우 SQLite FTS5로 업그레이드할 예정.

• 설계상 단일 사용자, 단일 머신용. 다중 사용자를 지원하려면 SQLite를 Postgres로 교체하고 사용자 컬럼을 추가해야 함.

라이선스

MIT