personal-mcp-fastmcp

왕초보용 MCP 캐릭터 — FastMCP(Python) 골격 ~50줄짜리 server.py 하나. Windows · macOS · Linux 모두 동일하게 동작.

0. 사전 준비 (한 번만)

✅ Python 트랙은 Windows 네이티브에서도 잘 동작합니다 (Rails와 달리). WSL2 없이 PowerShell만으로 OK.

Python 3.11+ 설치 확인

python3 --version   # 또는 python --version (Windows)
# 3.11 이상이어야 함. 없으면 https://python.org 에서 설치

uv 설치 (Python 패키지 매니저, 가장 빠름)

macOS:

brew install uv
# 또는: curl -LsSf https://astral.sh/uv/install.sh | sh

Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# 새 PowerShell 창 열어서 확인

확인:

uv --version
uv python install 3.12   # Python 자동 설치/관리도 uv가 해줌 (옵션)

⚠️ macOS에서 Claude Desktop이 uv를 못 찾는 경우(ENOENT 에러) → sudo ln -s ~/.local/bin/uv /usr/local/bin/uv 한 번 실행. macOS GUI 앱이 PATH를 다르게 읽기 때문.

🪟 Windows에서 uv가 PATH에 없으면 새 PowerShell을 열어보세요. 여전히 없으면 where uv로 위치 확인 후 PATH에 추가.

---

1. 5분 시작

의존성 설치

cd personal-mcp-fastmcp
uv sync

Claude Desktop에 자동 등록 (권장 — Win/Mac 둘 다 자동)

uv run fastmcp install claude-desktop server.py --server-name my-character

이 명령 하나로:

• Claude Desktop config 파일 위치를 OS별로 자동 탐지
• mcpServers 항목 자동 추가
• 의존성 경로 자동 설정

Claude Desktop 재시작 → 채팅창 입력란 좌측 하단에 🔨 아이콘이 보이면 성공.

동작 확인

Claude에 입력:

hello 도구 호출해줘

정상 응답: "안녕! 이게 너의 첫 MCP 캐릭터야."

---

2. 수동 설정 (자동이 실패할 때)

Claude Desktop 설정 파일 위치:

OS	경로
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

mcpServers 키에 추가:

macOS / Linux:

{
  "mcpServers": {
    "my-character": {
      "command": "uv",
      "args": [
        "--directory", "/Users/YOUR_NAME/personal-mcp-character/personal-mcp-fastmcp",
        "run", "python", "server.py"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "my-character": {
      "command": "uv",
      "args": [
        "--directory", "C:\\Users\\YOUR_NAME\\personal-mcp-character\\personal-mcp-fastmcp",
        "run", "python", "server.py"
      ]
    }
  }
}

---

3. 파일 구조

personal-mcp-fastmcp/
├── server.py                            # MCP 서버 본체 (~50줄)
├── gates/
│   ├── __init__.py
│   └── permission.py                    # read/write/danger 분기
├── pyproject.toml                       # 의존성 1개 (mcp[cli])
├── claude_desktop_config.example.json   # 수동 등록용 템플릿
└── README.md

---

4. 자주 쓰는 명령어 모음

작업	명령어 (모든 OS 동일)
의존성 설치	uv sync
Claude Desktop 자동 등록	uv run fastmcp install claude-desktop server.py --server-name my-character
MCP 인스펙터 (UI로 테스트)	uv run fastmcp dev server.py
서버만 직접 실행 (디버그)	uv run python server.py
도구 목록 확인 (다른 터미널)	echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | uv run python server.py
의존성 추가	uv add 패키지명
가상환경 활성화 (필요시)	macOS/Linux: source .venv/bin/activate · Windows: .venv\Scripts\activate

---

5. 본인 도구 추가하는 법

server.py에 데코레이터 한 줄 + 함수 하나:

@mcp.tool()
def my_tool(arg1: str) -> str:
    """이 도구가 무엇을 하는지 — Claude가 이걸 보고 판단합니다."""
    gate.check("read", action=f"my_tool: {arg1}")  # 위험도 분류
    return "결과"

위험도 세 가지:

• "read" — 조회만, 자동 통과
• "write" — 쓰기/추가, 5분 윈도우 자동 승인
• "danger" — 삭제/메일/결재, 매번 사용자 확인

---

6. 옵션 — 각자 환경에 맞게 추가

기본 골격에는 의도적으로 빠져있습니다. 본인 환경에 맞춰 채우세요.

시크릿 관리 (OS별)

macOS — Keychain:

security add-generic-password -s "notion-api" -a "$(whoami)" -w "secret_xxx"

import subprocess
def get_secret(name):
    return subprocess.run(
        ["security", "find-generic-password", "-s", name, "-w"],
        capture_output=True, text=True, check=True,
    ).stdout.strip()

Windows — Credential Manager:

# pip install keyring
import keyring
keyring.set_password("notion-api", "default", "secret_xxx")  # 한 번만
NOTION_KEY = keyring.get_password("notion-api", "default")

Linux — Secret Service (libsecret):

# pip install keyring secretstorage
# 위 keyring 코드 그대로 동작 (백엔드는 libsecret이 자동 선택됨)

옵시디언 vault 어댑터

from pathlib import Path
import os

VAULT = Path(os.environ.get("OBSIDIAN_VAULT", str(Path.home() / "obsidian-vault")))

@mcp.tool()
def search_vault(query: str) -> str:
    """옵시디언 vault에서 마크다운 메모 검색."""
    gate.check("read", action=f"vault search: {query}")
    matches = []
    for md in VAULT.rglob("*.md"):
        text = md.read_text(errors="ignore")
        if query.lower() in text.lower():
            matches.append(f"## {md.relative_to(VAULT)}\n{text[:500]}")
    return "\n\n---\n\n".join(matches[:5]) or "결과 없음"

Pathlib을 쓰면 Win/Mac/Linux 경로가 자동 호환됩니다.

HITL 채널 교체 (gates/permission.py의 _ask_user)

• macOS 알림: osascript -e 'display dialog "..." buttons {"거부","승인"}'
• Windows 알림: PowerShell [System.Windows.Forms.MessageBox]::Show(...)
• 크로스플랫폼: Telegram bot / Pushover / Slack webhook

---

7. 트러블슈팅

증상	원인 / 해결
Claude Desktop에 🔨 아이콘 안 보임	1. config 파일에 정확히 추가됐는지 확인 2. 설정 → 개발자 → 로그 확인 3. Claude Desktop 완전 종료 후 재시작
spawn uv ENOENT (macOS)	sudo ln -s ~/.local/bin/uv /usr/local/bin/uv (GUI 앱 PATH 이슈)
spawn uv ENOENT (Windows)	where uv로 경로 확인 후 config의 command에 절대경로 입력 (예: "C:\\Users\\me\\.local\\bin\\uv.exe")
한글 출력 깨짐	PYTHONIOENCODING=utf-8 환경변수 설정
mcp 패키지 import 에러	uv sync 다시 실행, Python 버전 3.11+ 확인

---

자매 프로젝트

• 같은 컨셉 Rails 8 버전: ../personal-mcp-rails/
• 블로그: MCP는 내 전용 캐릭터다