npm package: @kein.you/whooing-mcp
Description: MCP server for the Whooing (후잉) accounting service API
Latest version: 0.1.4

# 후잉 MCP 서버 (Whooing MCP Server)

[후잉(Whooing)](https://whooing.com) 가계부를 AI 에이전트(Claude 등)에서 사용할 수 있게 해주는 MCP 서버입니다.

자연어로 가계부를 입력할 수 있습니다:

> "오늘 스타벅스에서 5000원 카드로 결제했어. 후잉에 입력해줘"
>
> "이번주 쿠팡 결제내역 메일을 읽고 후잉에 입력해줘"

## 두 가지 실행 모드

| 모드 | 전송 방식 | 사용 환경 |
|------|-----------|-----------|
| **로컬 (stdio)** | 표준 입출력 | Claude Desktop, Claude Code 등 로컬 AI 클라이언트 |
| **리모트 (HTTP)** | Streamable HTTP | 외부 서버에 배포하여 claude.ai 등에서 원격 접속 |

## 사전 준비

- [Node.js](https://nodejs.org) 18 이상
- [후잉](https://whooing.com) 계정

## 후잉 토큰 발급

두 모드 모두 후잉 API 토큰이 필요합니다. 터미널에서 아래 명령을 실행하세요:

```bash
npx @kein.you/whooing-mcp auth
```

안내에 따라 진행합니다:
1. 브라우저가 열리면 후잉에 로그인합니다
2. 앱 승인 화면에서 **승인**을 누릅니다
3. 화면에 표시된 **PIN 번호**를 터미널에 입력합니다
4. `WHOOING_TOKEN`과 `WHOOING_TOKEN_SECRET` 값이 출력됩니다

---

## 로컬 모드 (stdio)

Claude Desktop, Claude Code 등 로컬에서 실행되는 AI 클라이언트에서 사용하는 방법입니다.

### Claude Desktop 설정

**Settings → Developer → Edit Config**를 열고 아래 내용을 추가하세요:

```json
{
  "mcpServers": {
    "whooing": {
      "command": "npx",
      "args": ["-y", "@kein.you/whooing-mcp"],
      "env": {
        "WHOOING_TOKEN": "발급받은 토큰",
        "WHOOING_TOKEN_SECRET": "발급받은 토큰 시크릿"
      }
    }
  }
}
```

설정 후 Claude Desktop을 **재시작**하면 연동이 완료됩니다.

### Claude Code 설정

```bash
claude mcp add whooing -- npx -y @kein.you/whooing-mcp
```

환경변수 `WHOOING_TOKEN`과 `WHOOING_TOKEN_SECRET`이 셸에 설정되어 있어야 합니다.

---

## 리모트 모드 (HTTP)

외부 서버에 배포하여 claude.ai 웹 등에서 원격으로 접속하는 방법입니다.

### 서버 설치 및 실행

```bash
# 소스 클론 및 빌드
git clone https://github.com/kein-you/WhooingMCP.git
cd WhooingMCP
npm install
npm run build

# 환경변수 설정 후 HTTP 모드로 실행
WHOOING_TOKEN="발급받은 토큰" \
WHOOING_TOKEN_SECRET="발급받은 토큰 시크릿" \
TRANSPORT=http \
PORT=3000 \
node dist/index.js
```

서버가 `http://0.0.0.0:3000/mcp` 에서 시작됩니다.

### 환경변수

| 변수 | 필수 | 설명 |
|------|------|------|
| `WHOOING_TOKEN` | O | 후잉 API 토큰 |
| `WHOOING_TOKEN_SECRET` | O | 후잉 API 토큰 시크릿 |
| `TRANSPORT` | O | `http`로 설정하면 HTTP 모드 (미설정 시 stdio) |
| `PORT` | - | HTTP 서버 포트 (기본값: `3000`) |

### 엔드포인트

| 메서드 | 경로 | 설명 |
|--------|------|------|
| `POST` | `/mcp` | MCP 요청 처리 |
| `GET` | `/health` | 헬스체크 |

### 프로덕션 배포 (예: systemd)

```ini
# /etc/systemd/system/whooing-mcp.service
[Unit]
Description=Whooing MCP Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/whooing-mcp
ExecStart=/usr/bin/node dist/index.js
Environment=TRANSPORT=http
Environment=PORT=3000
Environment=WHOOING_TOKEN=발급받은_토큰
Environment=WHOOING_TOKEN_SECRET=발급받은_토큰_시크릿
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable --now whooing-mcp
```

프로덕션 환경에서는 nginx 등의 리버스 프록시로 HTTPS를 적용하는 것을 권장합니다.

### claude.ai에서 연결

1. [claude.ai](https://claude.ai) → **Settings → Connectors → Add Custom Connector**
2. MCP 서버 URL 입력 (예: `https://your-domain.com/mcp`)

---

## 사용 예시

| 요청 | 설명 |
|------|------|
| "후잉 섹션 목록 보여줘" | 등록된 가계부(섹션) 목록 확인 |
| "후잉 계정 목록 보여줘" | 사용 가능한 계정(현금, 카드, 식비 등) 확인 |
| "오늘 점심 12000원 카드 결제 후잉에 입력해줘" | 거래 입력 |
| "이번 달 손익 보여줘" | 손익계산서 조회 |
| "최근 거래 내역 보여줘" | 최근 입력한 거래 확인 |

Gmail MCP와 함께 사용하면 메일에서 결제 내역을 읽어 자동으로 가계부에 입력할 수도 있습니다.

## 제공 기능

| 기능 | 설명 |
|------|------|
| 섹션 목록 조회 | 등록된 가계부(섹션) 목록 |
| 계정 목록 조회 | 자산, 부채, 수입, 비용 등 계정 목록 |
| 거래 입력 | 복식부기 방식으로 거래 생성 |
| 거래 조회 | 최근 거래 내역 확인 |
| 거래 삭제 | 잘못 입력한 거래 삭제 |
| 대차대조표 | 특정 시점의 자산/부채 현황 |
| 손익계산서 | 기간별 수입/지출 현황 |

## 문제 해결

### "Missing required environment variables" 오류
`WHOOING_TOKEN`과 `WHOOING_TOKEN_SECRET`이 올바르게 설정되었는지 확인하세요.

### 로컬 모드: Claude Desktop에서 후잉 도구가 보이지 않음
1. Claude Desktop을 재시작해 보세요
2. Settings → Developer에서 whooing 서버가 활성화되어 있는지 확인하세요
3. Node.js 18 이상이 설치되어 있는지 확인하세요: `node --version`

### 리모트 모드: 서버 상태 확인
```bash
curl http://localhost:3000/health
# 정상 응답: {"status":"ok"}
```

### 토큰 재발급
토큰이 만료되었거나 문제가 있으면 다시 발급받으세요:
```bash
npx @kein.you/whooing-mcp auth
```

## 라이선스

MIT