picgo-mcp

빠른 시작: 다음 프롬프트를 Coding Agent에게 보내세요: https://github.com/timerring/PicGo-MCP 에서 PicGo MCP Server를 설치하고 구성해 주세요.

PicGo Core를 프로세스에 직접 임베드하는 MCP stdio server입니다. Codex, Claude Desktop 등 MCP 클라이언트가 기존 PicGo 이미지 저장소 구성을 재사용할 수 있으며, PicGo 데스크톱이 실행 중일 필요도 없고 127.0.0.1:36677을 거치지도 않습니다.

기능

• PicGo Core 3를 직접 호출하며 데스크톱 의존성이 없습니다.

• 로컬 파일, file:// URL 및 HTTP(S) 이미지 URL을 지원합니다.

• 단일 이미지와 최대 20개의 이미지 일괄 업로드를 지원합니다.

• PicGo Desktop, PicGo Core 및 CLI 구성을 자동으로 발견합니다.

• 커스텀 업로드 파일명과 반환 형식을 지원합니다.

• 동시 호출을 자동으로 큐에 넣어 PicGo의 가변 업로드 상태가 서로 오염되지 않도록 합니다.

• 상태 도구는 token, secret 등 구성 값을 반환하지 않으며 사용자 홈 디렉터리를 ~로 표시합니다.

Related MCP server: flin-imgbb-mcp

환경 요구사항

• Node.js >=20.19.0

• 동작하는 PicGo 구성 파일

설치

소스에서 설치:

npm install
npm run build
npm install -g .

명령 사용 가능 여부 확인:

picgo-mcp --help

Codex에 설치

codex mcp add picgo -- picgo-mcp
codex mcp get picgo

MCP server를 추가한 후 새 작업을 만들거나 클라이언트를 새로고침하여 도구 목록을 다시 로드하세요.

기타 MCP 클라이언트

전역 설치 후 다음 stdio 구성을 사용할 수 있습니다:

{
  "mcpServers": {
    "picgo": {
      "command": "picgo-mcp"
    }
  }
}

구성 파일을 명시적으로 지정해야 하는 경우:

{
  "mcpServers": {
    "picgo": {
      "command": "picgo-mcp",
      "args": ["--config", "/path/to/picgo/config.json"]
    }
  }
}

환경 변수 PICGO_CONFIG_PATH를 설정할 수도 있습니다. --config는 환경 변수와 자동 발견보다 우선합니다.

PicGo 구성

기본적으로 다음 순서로 찾습니다:

• macOS: ~/Library/Application Support/picgo/data.json

• Windows: %APPDATA%/picgo/data.json

• Linux: $XDG_CONFIG_HOME/picgo/data.json 또는 ~/.config/picgo/data.json

• 모든 플랫폼: ~/.picgo/config.json

GitHub 이미지 저장소 예시

다음 예는 이미지를 저장소의 images/ 디렉터리에 업로드하고 jsDelivr를 통해 CDN 주소를 반환합니다:

{
  "picBed": {
    "uploader": "github",
    "current": "github",
    "github": {
      "repo": "OWNER/REPOSITORY",
      "branch": "main",
      "path": "images/",
      "customUrl": "https://cdn.jsdelivr.net/gh/OWNER/REPOSITORY@main",
      "token": "YOUR_GITHUB_TOKEN"
    }
  },
  "picgoPlugins": {},
  "settings": {
    "picgoMcp": {
      "uploadNameTemplate": "${dateTime}-${fileName}${extName}",
      "outputFormat": "${url}"
    }
  }
}

GitHub token은 대상 저장소에 대한 쓰기 권한이 있어야 합니다. 실제 token을 Git, Issue, 로그 또는 대화 기록에 커밋하지 마세요. 구성 파일 권한을 현재 사용자만 읽을 수 있도록 제한하세요:

chmod 600 ~/.picgo/config.json

PicGo Core 3가 이전 버전의 구성을 처음 읽을 때 uploader 구성과 내부 메타데이터를 보완할 수 있습니다. 이는 정상적인 자동 마이그레이션 동작입니다.

파일명 템플릿

설정 위치:

{
  "settings": {
    "picgoMcp": {
      "uploadNameTemplate": "${dateTime}-${fileName}${extName}"
    }
  }
}

지원 변수:

권장 설정:

${dateTime}-${fileName}${extName}

${dateTime}${extName}만 사용하면 같은 초에 업로드된 이미지의 파일명이 중복될 수 있습니다. 템플릿은 화이트리스트의 자리 표시자만 치환하고 JavaScript는 실행되지 않으며, 파일명을 통해 ../와 같은 추가 경로를 쓸 수 없습니다. 원격 디렉터리는 업로더의 path 구성을 사용해야 합니다.

출력 템플릿

설치 위치:

{
  "settings": {
    "picgoMcp": {
      "outputFormat": "${url}"
    }
  }
}

지원 변수:

• ${url}: 업로드 completed 후 이미지 URL.

• ${uploadedName}: `.확장자를 제외한 업로드된 파일명.

일반 형식:

${url}
![${uploadedName}](${url})

도구 응답에는 항상 이미지 정보, URL 배열, Markdown 및 템플릿으로 생성된 formattedOutput이 포함되므로 호출자는 필요에 따라 필드를 선택할 수 있습니다.

MCP 도구

upload_image

로컬 또는 원격 이미지 하나를 업로드합니다:

{
  "source": "/path/to/image.png"
}

upload_images

1–20장의 이미지를 일괄 업로드합니다:

{
  "sources": [
    "/path/to/first.png",
    "https://example.com/second.jpg"
  ]
}

get_picgo_status

구성 존재 여부, PicGo 버전, 현재 업로더, 구성된 필드 이름 및 사용 가능한 업로더를 반환합니다. 이 도구는 설정 값이나 호스트 자격 증명을 반환합니다.

업로드 결과 예시

{
  "images": [
    {
      "url": "https://cdn.example.com/images/2026-08-23-17-34-47-example.png",
      "fileName": "2026-08-23-17-34-47-example.png",
      "width": 800,
      "height": 600,
      "size": 123456
    }
  ],
  "urls": [
    "https://cdn.example.com/images/2026-08-23-17-34-47-example.png"
  ],
  "markdown": "![2026-08-23-17-34-47-example.png](https://cdn.example.com/images/2026-08-23-17-34-47-example.png)",
  "formattedOutput": "https://cdn.example.com/images/2026-08-23-17-34-47-example.png"
}

동작 방식

MCP 클라이언트는 일반적으로 picgo-mcp stdio 프로세스를 시작하고 현재 클라이언트 세션 동안 이를 재사용합니다. 업로드 도구를 호출할 때만 이미지를 읽고 이미지의 소스 및 호스트 서비스에 접근합니다. 클라이언트가 연결을 닫으면 server 프로세스는 종료되고 메모리를 해제합니다.

PicGo는 인스턴스에 가변 입력/출력 상태를 저장하므로, 이 프로젝트는 동시 업로드 요청을 직렬로 실행합니다.

보안 참고

• 명령 인수에 token을 전달하지 마세요. 자격 증명은 PicGo 구성으로 관리해야 합니다.

• MCP 도구는 호스트 자격 증명을 반환하지 않습니다. 상태 도구는 필드 이름만 반환합니다.

• 홈 디렉터리 경로는 도구 응답에서 ~로 대체됩니다.

• HTTP(S) 이미지는 PicGo가 먼저 다운로드한 후 구성된 호스트에 업로드됩니다.

• PicGo는 구성에 따라 plugin을 로드합니다. 신뢰할 수 있는 plugin만 설치하고 활성화하세요.

• stdio server를 신뢰할 수 없는 클라이언트에 노출하지 마세요.

PicGo 3.0.1의 의존성 트리에는 현재 image-size와 이전 버전 inquirer/tmp의 npm 보안 공지가 포함됩니다. 전자는 특수하게 제작된 이미지를 처리할 때 프로세스 서비스 거부를 유발할 수 있습니다. 후자는 이 프로젝트가 호출하지 않는 PicGo CLI의 상호작용 경로에 있습니다. 이러한 의존성은 PicGo 업스트림이 업그레이드해야 합니다.

개발 및 검증

npm install
npm test
npm run check
npm run build

현재 테스트는 구성 발견, MCP 도구 등록, 상태 마스킹, 업로드 입력 검증, 명명 템플릿, 출력 템플릿 및 릴리스 파일 개인정보 검사를 포함합니다.

License

MIT