> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ShortURL MCP 연동 가이드

> shorturl MCP 服务器集成

[MCP（Model Context Protocol）](https://modelcontextprotocol.io)는 Anthropic에서 출시한 모델 컨텍스트 프로토콜로, Claude, GPT 등 AI 모델이 표준화된 인터페이스를 통해 외부 도구를 호출할 수 있게 합니다. XHuoAPI에서 제공하는 ShortURL MCP Server를 통해 Claude Desktop, VS Code, Cursor 등 AI 클라이언트에서 직접 단축 URL을 생성할 수 있습니다.

## 기능 개요

ShortURL MCP Server는 다음과 같은 핵심 기능을 제공합니다:

* **단일 링크 단축** — 긴 URL을 짧고 공유하기 쉬운 단축 링크로 변환
* **대량 링크 단축** — 최대 10개의 URL을 한 번에 단축
* **사용 가이드** — 전체 사용 설명서 및 모범 사례 제공
* **API 정보** — API 서비스 상세 및 오류 코드 설명 확인

## 사전 준비

사용 전에 XHuoAPI API Token을 발급받아야 합니다:

1. [XHuoAPI 플랫폼](https://api.xhuoapi.ai)에서 회원가입 또는 로그인
2. [ShortURL API](https://api.xhuoapi.ai/documents/short-url) 페이지로 이동
3. 「Acquire」를 클릭하여 API Token 발급 (최초 신청 시 무료 할당량 제공)

## 설치 및 설정

### 방법 1: pip 설치 (권장)

```bash theme={null}
pip install mcp-shorturl
```

### 방법 2: 소스 코드 설치

```bash theme={null}
git clone https://github.com/XHuoAPI/ShortURLMCP.git
cd ShortURLMCP
pip install -e .
```

설치 완료 후 `mcp-shorturl` 명령어로 서비스를 시작할 수 있습니다.

## Claude Desktop에서 사용하기

Claude Desktop 설정 파일을 편집합니다:

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

다음 설정을 추가하세요:

```json theme={null}
{
  "mcpServers": {
    "shorturl": {
      "command": "mcp-shorturl",
      "env": {
        "XHuoAPI_API_TOKEN": "당신의 API Token"
      }
    }
  }
}
```

`uvx` 사용 시 (사전 패키지 설치 불필요):

```json theme={null}
{
  "mcpServers": {
    "shorturl": {
      "command": "uvx",
      "args": ["mcp-shorturl"],
      "env": {
        "XHuoAPI_API_TOKEN": "당신의 API Token"
      }
    }
  }
}
```

설정 저장 후 Claude Desktop을 재시작하면 대화 중 ShortURL 관련 도구를 사용할 수 있습니다.

## VS Code / Cursor에서 사용하기

프로젝트 루트 디렉터리에 `.vscode/mcp.json` 파일을 생성합니다:

```json theme={null}
{
  "servers": {
    "shorturl": {
      "command": "mcp-shorturl",
      "env": {
        "XHuoAPI_API_TOKEN": "당신의 API Token"
      }
    }
  }
}
```

또는 `uvx`를 사용할 경우:

```json theme={null}
{
  "servers": {
    "shorturl": {
      "command": "uvx",
      "args": ["mcp-shorturl"],
      "env": {
        "XHuoAPI_API_TOKEN": "당신의 API Token"
      }
    }
  }
}
```

## 사용 가능한 도구 목록

| 도구명                        | 설명                |
| -------------------------- | ----------------- |
| `shorturl_create`          | 단일 URL 단축         |
| `shorturl_batch_create`    | 최대 10개의 URL 대량 단축 |
| `shorturl_get_usage_guide` | 전체 사용 가이드 조회      |
| `shorturl_get_api_info`    | API 서비스 상세 조회     |

## 사용 예시

설정 완료 후 AI 클라이언트에서 자연어로 다음과 같이 기능을 호출할 수 있습니다:

* "이 링크를 단축해줘"
* "이 5개의 URL을 한꺼번에 단축해줘"
* "공유용 단축 링크를 생성해줘"

## 추가 정보

* GitHub 저장소: [XHuoAPI/ShortURLMCP](https://github.com/XHuoAPI/ShortURLMCP)
* PyPI 패키지: [mcp-shorturl](https://pypi.org/project/mcp-shorturl/)
* API 문서: [단축 링크 생성 API](https://api.xhuoapi.ai/documents/short-url)