OpenGraph MCP 서버 (og-mcp)

og‑mcp는 모든 OpenGraph.io ( https://opengraph.io ) API 엔드포인트를 표준 MCP 인터페이스를 통해 AI 에이전트(예: Anthropic Claude, Cursor, LangGraph)가 사용할 수 있도록 만드는 모델 컨텍스트 프로토콜(MCP) 서버입니다.

왜 필요한가요? 이미 OpenGraph.io를 사용하여 링크 미리보기, HTML 스크래핑, 기사 텍스트 추출 또는 스크린샷 캡처를 수행하고 있다면, 이제 원시 API 키를 노출하지 않고도 자율 에이전트에 동일한 기능을 제공할 수 있습니다.

전역 설치

npm을 통해 이 패키지를 전역으로 설치할 수 있습니다:

npm install -g opengraph-io-mcp

빠른 설치

CLI 설치 프로그램 (권장)

지원되는 모든 클라이언트에 대해 OpenGraph MCP를 구성하는 가장 쉬운 방법입니다:

# Interactive mode - guides you through setup
npx opengraph-io-mcp-install

# Direct mode - specify client and app ID
npx opengraph-io-mcp-install --client cursor --app-id YOUR_APP_ID

지원되는 클라이언트: cursor, claude-desktop, windsurf, vscode, zed, jetbrains

Claude Desktop 확장 프로그램

Claude Desktop 사용자의 경우, 릴리스 페이지에서 원클릭 설치를 위한 .mcpb 확장 프로그램을 다운로드할 수도 있습니다.

클라이언트 구성

아래의 모든 구성은 호스팅된 HTTPS 전송(권장)을 사용합니다. YOUR_OPENGRAPH_APP_ID를 귀하의 OpenGraph.io 앱 ID로 바꾸십시오. 로컬 설치나 npx가 필요하지 않으며, 클라이언트를 호스팅된 URL로 지정하기만 하면 됩니다.

Claude Desktop

구성 위치:

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

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

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

Claude Code

한 줄 명령어로 설치:

claude mcp add --transport http --header "x-app-id: YOUR_OPENGRAPH_APP_ID" opengraph https://mcp.opengraph.io/mcp

Cursor

구성 위치: ~/.cursor/mcp.json

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

VS Code

구성 위치: .vscode/mcp.json (프로젝트 디렉토리 내)

VS Code는 보안 자격 증명 처리를 위한 입력 프롬프트를 지원합니다:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "opengraph-app-id",
      "description": "OpenGraph App ID",
      "password": true
    }
  ],
  "servers": {
    "opengraph": {
      "type": "http",
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "${input:opengraph-app-id}"
      }
    }
  }
}

Windsurf

구성 위치: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

JetBrains AI Assistant

JetBrains AI Assistant MCP 구성에 추가하십시오:

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

Zed

구성 위치: ~/.config/zed/settings.json

참고: Zed는 mcpServers 대신 context_servers를 사용합니다:

{
  "context_servers": {
    "opengraph": {
      "transport": "http",
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

사용 가능한 도구

OpenGraph.io 데이터 도구

이미지 생성 도구

이미지 생성

og-mcp 서버는 소셜 미디어 카드, 아키텍처 다이어그램, 아이콘 등을 만드는 데 완벽한 강력한 AI 기반 이미지 생성 기능을 포함합니다.

Generate Image

자연어 프롬프트나 다이어그램 코드로 이미지를 생성합니다.

지원되는 이미지 유형 (kind):

• illustration - 범용 AI 생성 이미지

• diagram - Mermaid, D2 또는 Vega 구문을 사용한 기술 다이어그램

• icon - 앱 아이콘 및 로고

• social-card - 소셜 공유에 최적화된 OG 이미지

• qr-code - 스타일링 옵션이 포함된 QR 코드

사전 설정된 가로세로 비율:

• 소셜: og-image, twitter-card, twitter-post, linkedin-post, facebook-post, instagram-square, instagram-portrait, instagram-story, youtube-thumbnail

• 표준: wide, square, portrait

• 아이콘: icon-small, icon-medium, icon-large

스타일 사전 설정: github-dark, github-light, notion, vercel, linear, stripe, neon-cyber, pastel, minimal-mono, corporate, startup, documentation, technical

다이어그램 템플릿: auth-flow, oauth2-flow, crud-api, microservices, ci-cd, gitflow, database-schema, state-machine, user-journey, cloud-architecture, system-context

사용 예시:

// Generate a social card
generateImage({
  prompt: "A modern tech startup hero image with abstract geometric shapes",
  kind: "social-card",
  aspectRatio: "og-image",
  stylePreset: "vercel",
  brandColors: ["#0070F3", "#000000"]
})

// Generate a diagram from Mermaid syntax
generateImage({
  prompt: "graph TD; A[User] --> B[API]; B --> C[Database]",
  kind: "diagram",
  diagramSyntax: "mermaid",
  stylePreset: "github-dark"
})

Iterate Image

기존에 생성된 이미지를 개선하거나 수정합니다.

사용 사례:

• 특정 부분 편집: "배경을 파란색으로 변경"

• 스타일 변경 적용: "더 미니멀하게 만들어줘"

• 문제 수정: "텍스트 제거", "아이콘을 더 크게 만들어줘"

• 특정 좌표로 자르기

예시:

iterateImage({
  sessionId: "uuid-from-generate",
  assetId: "uuid-from-generate",
  prompt: "Change the primary color to #0033A0 and add a subtle drop shadow"
})

Inspect Image Session

세션 세부 정보를 검토하고 반복 작업을 위한 자산 ID를 찾습니다.

반환 값:

• 세션 메타데이터 (생성 시간, 이름, 상태)

• 프롬프트, 툴체인 및 상태를 포함한 모든 자산 목록

• 반복 기록을 보여주는 부모-자식 관계

예시:

inspectImageSession({
  sessionId: "uuid-from-generate"
})

Export Image Asset

세션 및 자산 ID별로 생성된 이미지 자산을 내보냅니다. 메타데이터(형식, 크기, 용량)와 함께 이미지를 인라인 base64로 반환합니다.

로컬에서 실행할 때(stdio 전송), 선택적으로 destinationPath를 제공하여 이미지를 디스크에 저장할 수 있습니다. 호스팅/HTTP 전송 시에는 경로가 무시되고 이미지만 인라인으로 반환됩니다.

예시:

// Inline only (works everywhere)
exportImageAsset({
  sessionId: "uuid-from-generate",
  assetId: "uuid-from-generate"
})

// Save to disk (stdio/local only)
exportImageAsset({
  sessionId: "uuid-from-generate",
  assetId: "uuid-from-generate",
  destinationPath: "/Users/me/project/images/hero.png"
})

작동 원리

og-mcp의 이미지 생성 도구로 생성된 다이어그램

og-mcp 서버는 AI 클라이언트(Claude 또는 기타 LLM)와 OpenGraph.io API 사이의 가교 역할을 합니다:

1. AI 클라이언트가 사용 가능한 MCP 함수 중 하나를 호출합니다.

2. og-mcp 서버가 요청을 수신하고 OpenGraph.io API에 맞게 형식을 지정합니다.

3. OpenGraph.io가 요청을 처리하고 데이터를 반환합니다.

4. og-mcp가 응답을 AI 클라이언트에 적합한 형식으로 변환합니다.

5. AI 클라이언트가 사용할 준비가 된 구조화된 데이터를 수신합니다.

이 추상화 계층은 API 키가 AI에 직접 노출되는 것을 방지하면서 OpenGraph.io 기능에 대한 전체 액세스 권한을 제공합니다.

설정 및 실행

1. 이 저장소를 복제합니다.

2. 종속성을 설치합니다:

   npm install

3. TypeScript 코드를 빌드합니다:

   npm run build

4. 서버를 시작합니다:

   npm start

서버는 기본적으로 3010 포트에서 실행됩니다(PORT 환경 변수를 통해 구성 가능).

구성

서버가 제대로 작동하려면 OpenGraph.io 앱 ID가 필요합니다. 다음과 같은 방법으로 제공할 수 있습니다:

1. 환경 변수 사용: .env 파일이나 환경 변수에 OPENGRAPH_APP_ID 또는 APP_ID 설정

2. stdio 전송과 함께 명령줄 인수 사용: --app-id YOUR_APP_ID

3. SSE 전송 사용 시: URL에 쿼리 매개변수로 포함 (?app_id=YOUR_APP_ID)

.env 파일 예시:

OPENGRAPH_APP_ID=your_app_id_here
# or
APP_ID=your_app_id_here

전송 옵션

Stdio 전송 (권장)

명령줄 사용 및 npm 전역 설치의 경우, 서버를 stdio 전송으로 실행할 수 있습니다:

npm run start:stdio

명령줄 인수를 통해 OpenGraph API 키를 직접 전달할 수 있습니다:

npm run start:stdio -- --app-id YOUR_APP_ID

전역으로 설치된 경우:

opengraph-io-mcp --app-id YOUR_APP_ID

이 모드를 사용하면 MCP를 사용하는 다른 애플리케이션에서 서버를 직접 호출할 수 있습니다.

HTTP/SSE 전송

이 방법은 HTTP를 통해 액세스할 수 있고 스트리밍을 위해 SSE를 사용하는 웹 서버를 실행합니다:

npm start

문제 해결

• 도구가 표시되지 않으면 서버가 실행 중인지, Cursor에서 URL이 올바르게 구성되었는지 확인하십시오.

• 연결 또는 권한 부여 문제가 있는지 서버 로그를 확인하십시오.

• Claude가 이름별로 특정 도구를 사용하도록 지시받았는지 확인하십시오.