Experience Memory MCP

사진과 짧은 메모를 하나의 경험 기억으로 저장하고, 나중에 자연어로 다시 찾는 MCP 서버입니다.

이 MVP는 호출 LLM 위임형입니다. 카카오톡/ChatGPT/Claude 같은 대화 중인 LLM이 사진과 메모를 보고 제목, 요약, 태그, 감정을 정리한 뒤 MCP tool을 호출합니다. MCP 서버는 AI API를 다시 호출하지 않고, 사진 원본과 Markdown 메모를 Google Drive에 저장하고 검색용 메타데이터를 저장합니다.

Tools

• connectGoogleDrive: 현재 사용자의 Google Drive 연결 URL 생성
• saveExperienceMemory: 사진과 사용자 메모 저장
• searchExperienceMemories: 자연어로 경험 검색

Setup

npm install
cp .env.example .env

.env에 Google Drive OAuth 값을 설정합니다. DATABASE_URL이 있으면 PostgreSQL을 사용하고, 없으면 PlayMCP in KC 제출용 local JSON 저장소를 사용합니다.

TOKEN_ENCRYPTION_KEY=
PORT=8000
MCP_HTTP_PATH=/mcp
HEALTH_PATH=/healthz
GOOGLE_OAUTH_CALLBACK_PATH=/oauth/google/callback
EXPERIENCE_MEMORY_DATA_DIR=/tmp/experience-memory
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

Google Drive 연동은 다중 사용자 actor 방식을 기본으로 사용합니다. 각 사용자가 connectGoogleDrive tool이 반환하는 Google OAuth URL을 열어 로그인하면, actor별 refresh token과 Drive root folder id가 암호화 저장됩니다.

단일 사용자 .env 방식도 로컬 테스트용으로만 지원합니다. 이 경우 GOOGLE_REFRESH_TOKEN, GOOGLE_DRIVE_ROOT_FOLDER_ID에 들어간 계정의 Drive에 저장되므로 public/multi-user 배포에는 사용하지 않습니다.

Google Drive 연결 전에는 connectGoogleDrive로 사용자 개인 Drive를 먼저 연결해야 합니다.

Google Drive 연결

Google Cloud Console에서 OAuth Client를 만들고 Google Drive API를 활성화합니다. Authorized redirect URI에는 아래 값을 추가합니다.

http://localhost:53682/oauth2callback

.env에 GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI를 채운 뒤 아래 명령을 실행합니다.

npm run google:auth

브라우저에서 Google Drive 접근을 허용하면 터미널에 아래 값이 출력됩니다.

GOOGLE_REFRESH_TOKEN=...
GOOGLE_DRIVE_ROOT_FOLDER_ID=...

이 값을 .env에 추가하면 MCP가 해당 Google 계정의 Drive에 사진과 Markdown 메모를 저장합니다. 권한은 전체 Drive 접근이 아니라 앱이 만든 파일 중심의 drive.file scope를 사용합니다.

다중 사용자 연결

actor별 Google Drive 연결을 로컬에서 저장하려면 .env에 TOKEN_ENCRYPTION_KEY, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET을 설정한 뒤 아래처럼 실행합니다.

npm run google:auth -- --actor-provider kakao --actor-id kakao-user-id

연결이 완료되면 refresh token과 Drive root folder id가 저장소에 암호화 저장됩니다. MCP를 stdio로 해당 actor에 고정 실행할 때는 아래 환경변수를 지정합니다.

EXPERIENCE_MEMORY_ACTOR_PROVIDER=kakao
EXPERIENCE_MEMORY_ACTOR_ID=kakao-user-id

PlayMCP 같은 HTTP MCP host에서 사용자 식별값을 헤더로 전달하면 MCP 서버가 actor별 Drive 연결을 선택합니다. 기본 후보 헤더는 x-playmcp-user-id, x-kakao-user-id, x-mcp-user-id, x-user-id, mcp-user-id입니다. 실제 헤더명이 다르면 아래처럼 지정합니다.

EXPERIENCE_MEMORY_ACTOR_PROVIDER=kakao
EXPERIENCE_MEMORY_ACTOR_HEADER=x-playmcp-user-id

Run

npm run db:check
npm run dev
npm run build
npm start

기본 실행은 PlayMCP in KC 배포용 HTTP transport입니다.

GET  /
GET  /healthz
POST /
POST /mcp

로컬 Codex/Claude Desktop처럼 stdio transport가 필요하면 아래 명령을 사용합니다.

npm run dev:stdio
npm run start:stdio

PlayMCP in KC 배포

PlayMCP in KC의 "Git 소스 빌드" 방식으로 등록할 수 있습니다.

• Git URL: 이 저장소 URL
• 브랜치 / ref: 배포할 브랜치
• Dockerfile 경로: Dockerfile
• Endpoint path: 발급된 Endpoint URL 뒤의 /mcp
• Health check path: /healthz

Docker 컨테이너는 기본적으로 PORT=8000에서 HTTP MCP endpoint를 엽니다. PlayMCP in KC 등록 화면의 container_port도 8000으로 둡니다.

공모전 제출용 Docker 이미지는 외부 DB 없이 뜰 수 있도록 local JSON 저장소를 사용합니다.

EXPERIENCE_MEMORY_DATA_DIR=/tmp/experience-memory

이 모드는 컨테이너 재시작/재배포 시 데이터가 유지된다는 보장이 없습니다. 실제 운영 또는 장기 유지 단계에서는 외부 PostgreSQL을 만들고 아래처럼 전환합니다.

DATABASE_URL=postgres://USER:PASSWORD@HOST:5432/experience_memory

PlayMCP in KC 입력 예시

기본 정보:

• MCP 서버 이름: experience-memory-mcp
• 설명: 사진과 메모를 Google Drive에 저장하고 자연어로 경험 기억을 검색하는 MCP 서버
• Git URL: https://github.com/jih19984/experience-memory-mcp.git
• 브랜치 / ref: main
• Dockerfile 경로: Dockerfile
• PAT: public repo라 비움
• container_port: 8000

환경변수:

MCP_HTTP_PATH=/mcp
HEALTH_PATH=/healthz
GOOGLE_OAUTH_CALLBACK_PATH=/oauth/google/callback
EXPERIENCE_MEMORY_DATA_DIR=/tmp/experience-memory

시크릿:

TOKEN_ENCRYPTION_KEY=...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

중요: GOOGLE_REFRESH_TOKEN과 GOOGLE_DRIVE_ROOT_FOLDER_ID는 PlayMCP in KC 등록 화면에 넣지 않습니다. 이 값들은 각 사용자가 Google OAuth를 완료한 뒤 사용자별로 저장됩니다.

Endpoint URL이 발급되면 Google Cloud Console의 OAuth Client에 아래 Authorized redirect URI를 추가합니다.

https://<발급받은-endpoint-host>/oauth/google/callback

그 뒤 사용자가 처음 저장하려 할 때 connectGoogleDrive tool을 호출해 개인 Google Drive를 연결합니다.

MCP 설정 예시

stdio transport를 사용하는 MCP host에서는 아래처럼 설정합니다.

{
  "mcpServers": {
    "experience-memory": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "DATABASE_URL": "...",
        "GOOGLE_CLIENT_ID": "...",
        "GOOGLE_CLIENT_SECRET": "...",
        "GOOGLE_REFRESH_TOKEN": "...",
        "GOOGLE_DRIVE_ROOT_FOLDER_ID": "..."
      }
    }
  }
}

Example

{
  "imagePath": "/Users/me/Pictures/han-river.jpg",
  "userNote": "오늘 한강에서 뛰었는데 힘들었지만 야경이 좋아서 버텼어.",
  "title": "한강 야경 러닝",
  "summary": "힘들었지만 한강 야경 덕분에 끝까지 버틴 러닝 경험.",
  "tags": ["한강", "러닝", "야경"],
  "mood": ["힘듦", "만족", "개운함"],
  "occurredAt": "2026-07-08",
  "locationHint": "한강"
}

응답:

{
  "memoryId": "...",
  "title": "한강 야경 러닝",
  "summary": "힘들었지만 한강 야경 덕분에 끝까지 버틴 러닝 경험.",
  "tags": ["한강", "러닝", "야경"],
  "mood": ["힘듦", "만족", "개운함"],
  "driveUrl": "https://drive.google.com/..."
}

Notes

• 클라우드 환경에서는 imagePath보다 imageUrl 또는 imageBase64 입력이 안전합니다.
• 사진 원본을 Drive에 저장하려면 MCP 서버가 실제 이미지 bytes에 접근할 수 있어야 합니다.
• DB 저장 실패 시 업로드된 Drive 파일 삭제를 시도합니다.