npm package: @makerjun/mcp-threads-server
Description: MCP server for interacting with Threads API
Author: makerjun
Latest version: 1.0.1

# Threads MCP 서버

이 프로젝트는 Model Context Protocol(MCP)을 사용하여 Threads API와 상호작용하는 서버입니다. 클라이언트(예: Claude)에서 Threads의 사용자 프로필 정보를 조회하고, 게시물을 포스팅하는 기능을 제공합니다.

## 설치

### npm을 통한 글로벌 설치

```bash
# npm 글로벌 설치
npm install -g @makerjun/mcp-threads-server

# 또는 npx를 사용하여 바로 실행 (권장)
npx @makerjun/mcp-threads-server
```

### 직접 소스코드에서 설치

```bash
# 저장소 클론
git clone https://github.com/makerjun/mcp-threads-server.git
cd mcp-threads-server

# 프로젝트 의존성 설치
npm install
```

## 설정

### 방법 1: .env 파일 사용 (개발용)

1. 프로젝트 루트 디렉토리에 `.env` 파일을 생성하고 다음 내용을 추가합니다:

```
# Threads API 액세스 토큰
THREADS_ACCESS_TOKEN=your_access_token_here
```

2. `your_access_token_here`를 실제 Threads API 액세스 토큰으로 대체합니다.

### 방법 2: Claude Desktop 설정 (권장)

Claude Desktop의 설정 파일에 액세스 토큰을 직접 포함시키는 방법입니다:

1. Claude Desktop 설정 파일 위치:

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

2. 다음과 같이 설정 파일을 수정합니다:

```json
{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@makerjun/mcp-threads-server"],
      "env": {
        "THREADS_ACCESS_TOKEN": "여기에_실제_액세스_토큰을_입력하세요"
      }
    }
  }
}
```

3. `여기에_실제_액세스_토큰을_입력하세요`를 실제 Threads API 액세스 토큰으로 대체합니다.

4. Claude 앱을 재시작합니다.

이 방법을 사용하면 Claude에서 액세스 토큰을 매번 입력하지 않아도 됩니다.

## 프로젝트에서 직접 빌드 및 실행

```bash
# 프로젝트 빌드
npm run build

# 서버 실행
npm start

# 또는 개발 모드로 실행 (파일 변경 감지 및 자동 재시작)
npm run dev:watch
```

## MCP 클라이언트 설정

Claude 데스크톱 앱과 같은 MCP 클라이언트에서 이 서버를 사용하는 방법:

### 1. npx를 이용한 방법 (권장)

```json
{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@makerjun/mcp-threads-server"],
      "env": {
        "THREADS_ACCESS_TOKEN": "여기에_실제_액세스_토큰을_입력하세요"
      }
    }
  }
}
```

### 2. 로컬 설치를 이용한 방법

```json
{
  "mcpServers": {
    "threads": {
      "command": "node",
      "args": ["/절대/경로/mcp-threads-test-v1/build/index.js"],
      "env": {
        "THREADS_ACCESS_TOKEN": "여기에_실제_액세스_토큰을_입력하세요"
      }
    }
  }
}
```

## 사용 가능한 도구

현재 서버는 다음 도구를 제공합니다:

### 프로필 도구

1. `getMyThreadsProfile`: 액세스 토큰을 사용하여 Threads 사용자 ID와 이름을 가져옵니다.

   - 매개변수: `accessToken`(문자열) - Threads API 액세스 토큰 (환경 변수에 토큰이 설정되지 않은 경우에만 필요)

2. `getThreadsProfile`: 환경 변수에 설정된 액세스 토큰을 사용하여 Threads 사용자 ID와 이름을 가져옵니다.
   - 매개변수: 없음 (환경 변수에 액세스 토큰이 설정되어 있어야 함)

### 게시물 작성 도구

3. `createTextPost`: 텍스트 전용 게시물을 작성하고 게시합니다.

   - 매개변수:
     - `text`(문자열) - 게시물 내용 (최대 500자)
     - `accessToken`(문자열, 선택 사항) - Threads API 액세스 토큰 (환경 변수에 설정되지 않은 경우 필요)

4. `createImagePost`: 이미지와 텍스트가 포함된 게시물을 작성하고 게시합니다.
   - 매개변수:
     - `imageUrl`(문자열) - 이미지 URL (공개적으로 접근 가능해야 함)
     - `text`(문자열, 선택 사항) - 게시물 텍스트 내용 (최대 500자)
     - `accessToken`(문자열, 선택 사항) - Threads API 액세스 토큰 (환경 변수에 설정되지 않은 경우 필요)

### 고급 게시물 작성 도구 (2단계 프로세스)

5. `createTextContainer`: 텍스트 미디어 컨테이너를 생성합니다 (게시물 작성의 첫 번째 단계).

   - 매개변수:
     - `text`(문자열) - 게시물 내용 (최대 500자)
     - `accessToken`(문자열, 선택 사항) - Threads API 액세스 토큰 (환경 변수에 설정되지 않은 경우 필요)

6. `publishContainer`: 이전에 생성된 미디어 컨테이너를 게시합니다 (게시물 작성의 두 번째 단계).
   - 매개변수:
     - `containerId`(문자열) - 컨테이너 ID (createTextContainer 또는 createImageContainer에서 반환됨)
     - `accessToken`(문자열, 선택 사항) - Threads API 액세스 토큰 (환경 변수에 설정되지 않은 경우 필요)

## 향후 계획

- 게시물 조회 기능 추가
- 댓글 및 좋아요 기능 추가