# 원격 MCP 서버 설정 가이드
이 가이드는 로컬이 아닌 원격지에서 `logseq-mcp` 서버에 접근하는 방법을 설명합니다.
## 📋 목차
1. [개요](#개요)
2. [서버 실행 방법](#서버-실행-방법)
3. [클라이언트 설정](#클라이언트-설정)
- [VS Code](#vs-code)
- [Claude Desktop](#claude-desktop)
- [Cursor](#cursor)
- [Windsurf](#windsurf)
- [Cline (VS Code 확장)](#cline-vs-code-확장)
4. [환경 변수](#환경-변수)
5. [보안 고려사항](#보안-고려사항)
6. [문제 해결](#문제-해결)
---
## 개요
`logseq-mcp`는 두 가지 트랜스포트 모드를 지원합니다:
| 모드 | 용도 | 프로토콜 |
|------|------|----------|
| **STDIO** (기본) | 로컬 VS Code 통합 | 표준 입출력 |
| **HTTP** | 원격 접속 | SSE / Streamable HTTP |
## 서버 실행 방법
### 1. 로컬 STDIO 모드 (기본)
```bash
# 개발 모드
pnpm start:dev
# 프로덕션 모드
pnpm build && pnpm start:prod
```
### 2. HTTP 서버 모드 (원격 접속용)
```bash
# 개발 모드
pnpm start:http:dev
# 프로덕션 모드
pnpm build && pnpm start:http:prod
```
HTTP 서버가 시작되면 다음 엔드포인트가 활성화됩니다:
| 엔드포인트 | 설명 |
|------------|------|
| `http://HOST:PORT/sse` | SSE 연결 엔드포인트 |
| `http://HOST:PORT/messages` | SSE 메시지 전송 엔드포인트 |
| `http://HOST:PORT/mcp` | Streamable HTTP 엔드포인트 |
### 3. 환경 변수로 커스텀 설정
```bash
# 커스텀 포트와 호스트로 실행
MCP_TRANSPORT=http \
MCP_PORT=8080 \
MCP_HOST=0.0.0.0 \
LOGSEQ_HOST=192.168.1.100 \
LOGSEQ_PORT=12315 \
LOGSEQ_TOKEN=your-token \
pnpm start:http:prod
```
---
## 클라이언트 설정
### VS Code
원격 MCP 서버에 접속하려면 VS Code의 `.vscode/mcp.json` 파일을 설정합니다.
#### SSE 방식 (권장)
```json
{
"servers": {
"logseq-mcp-remote": {
"type": "sse",
"url": "http://서버IP:3100/sse"
}
}
}
```
#### Streamable HTTP 방식
```json
{
"servers": {
"logseq-mcp-remote": {
"type": "http",
"url": "http://서버IP:3100/mcp"
}
}
}
```
#### 실제 예시
```json
{
"servers": {
"logseq-mcp-remote": {
"type": "sse",
"url": "http://192.168.1.100:3100/sse"
}
}
}
```
---
### Claude Desktop
Claude Desktop 앱에서 원격 MCP 서버에 접속하려면 설정 파일을 수정합니다.
#### 설정 파일 위치
| OS | 경로 |
|----|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
#### SSE 방식 설정
```json
{
"mcpServers": {
"logseq-mcp": {
"type": "sse",
"url": "http://서버IP:3100/sse"
}
}
}
```
#### 실제 예시
```json
{
"mcpServers": {
"logseq-mcp": {
"type": "sse",
"url": "http://192.168.1.100:3100/sse"
}
}
}
```
> **참고**: 설정 변경 후 Claude Desktop을 재시작해야 합니다.
---
### Cursor
Cursor IDE에서 원격 MCP 서버에 접속하는 방법입니다.
#### 설정 파일 위치
| OS | 경로 |
|----|------|
| macOS | `~/.cursor/mcp.json` |
| Windows | `%USERPROFILE%\.cursor\mcp.json` |
| Linux | `~/.cursor/mcp.json` |
#### SSE 방식 설정
```json
{
"mcpServers": {
"logseq-mcp": {
"type": "sse",
"url": "http://서버IP:3100/sse"
}
}
}
```
#### 실제 예시
```json
{
"mcpServers": {
"logseq-mcp": {
"type": "sse",
"url": "http://192.168.1.100:3100/sse"
}
}
}
```
> **참고**: Cursor 설정에서 MCP 기능이 활성화되어 있어야 합니다.
> Settings → Features → MCP Servers → Enable 확인
---
### Windsurf
Windsurf IDE에서 원격 MCP 서버에 접속하는 방법입니다.
#### 설정 파일 위치
| OS | 경로 |
|----|------|
| macOS | `~/.codeium/windsurf/mcp_config.json` |
| Windows | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
| Linux | `~/.codeium/windsurf/mcp_config.json` |
#### SSE 방식 설정
```json
{
"mcpServers": {
"logseq-mcp": {
"type": "sse",
"url": "http://서버IP:3100/sse"
}
}
}
```
#### 실제 예시
```json
{
"mcpServers": {
"logseq-mcp": {
"type": "sse",
"url": "http://192.168.1.100:3100/sse"
}
}
}
```
---
### Cline (VS Code 확장)
Cline VS Code 확장에서 원격 MCP 서버에 접속하는 방법입니다.
#### 설정 방법
1. VS Code에서 Cline 확장 설치
2. Cline 사이드바 열기
3. 설정 (⚙️) → MCP Servers 클릭
4. "Edit MCP Settings" 클릭
#### 설정 파일 위치
| OS | 경로 |
|----|------|
| macOS | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
| Windows | `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json` |
| Linux | `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
#### SSE 방식 설정
```json
{
"mcpServers": {
"logseq-mcp": {
"type": "sse",
"url": "http://서버IP:3100/sse"
}
}
}
```
#### 실제 예시
```json
{
"mcpServers": {
"logseq-mcp": {
"type": "sse",
"url": "http://192.168.1.100:3100/sse"
}
}
}
```
---
### 클라이언트 설정 요약
| 클라이언트 | 설정 파일 | 트랜스포트 |
|------------|----------|-----------|
| VS Code | `.vscode/mcp.json` | SSE, HTTP |
| Claude Desktop | `claude_desktop_config.json` | SSE |
| Cursor | `~/.cursor/mcp.json` | SSE |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | SSE |
| Cline | `cline_mcp_settings.json` | SSE |
---
## 환경 변수
### 서버 설정
| 변수명 | 기본값 | 설명 |
|--------|--------|------|
| `MCP_TRANSPORT` | `stdio` | 트랜스포트 모드 (`stdio` 또는 `http`) |
| `MCP_PORT` | `3100` | HTTP 서버 포트 |
| `MCP_HOST` | `0.0.0.0` | HTTP 서버 바인딩 호스트 |
| `MCP_CORS_ORIGINS` | `*` | CORS 허용 오리진 (쉼표로 구분) |
### Logseq 연결 설정
| 변수명 | 기본값 | 설명 |
|--------|--------|------|
| `LOGSEQ_HOST` | `127.0.0.1` | Logseq HTTP API 호스트 |
| `LOGSEQ_PORT` | `12315` | Logseq HTTP API 포트 |
| `LOGSEQ_TOKEN` | - | Logseq 인증 토큰 (필수) |
| `PROJECT_NAME` | `dev-project` | 프로젝트 페이지 이름 |
| `DOCS_PATH` | `./concepts` | 개념 문서 경로 |
### .env 파일 예시
```env
# MCP 서버 설정
MCP_TRANSPORT=http
MCP_PORT=3100
MCP_HOST=0.0.0.0
MCP_CORS_ORIGINS=http://localhost:*,vscode-webview://*
# Logseq 연결 설정
LOGSEQ_HOST=127.0.0.1
LOGSEQ_PORT=12315
LOGSEQ_TOKEN=your-logseq-token
# 프로젝트 설정
PROJECT_NAME=ego
DOCS_PATH=/path/to/concepts
```
---
## 보안 고려사항
### ⚠️ 중요 보안 경고
원격 MCP 서버를 운영할 때 다음 사항을 반드시 고려하세요:
### 1. 네트워크 보안
```bash
# 특정 IP만 바인딩 (권장)
MCP_HOST=192.168.1.100 # 특정 인터페이스만
# 방화벽 설정 (예: ufw)
sudo ufw allow from 192.168.1.0/24 to any port 3100
```
### 2. CORS 설정
```bash
# 특정 오리진만 허용 (권장)
MCP_CORS_ORIGINS=http://192.168.1.50:*,vscode-webview://*
```
### 3. HTTPS 사용 (프로덕션)
프로덕션 환경에서는 리버스 프록시(nginx, Caddy 등)를 사용하여 HTTPS를 적용하세요:
```nginx
# nginx 예시
server {
listen 443 ssl;
server_name mcp.example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://127.0.0.1:3100;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_buffering off;
proxy_cache off;
}
}
```
### 4. 인증 추가 (선택)
추가적인 보안이 필요한 경우, 인증 가드를 구현할 수 있습니다.
---
## 문제 해결
### 연결이 안 되는 경우
1. **서버가 실행 중인지 확인**
```bash
curl http://서버IP:3100/sse
```
2. **방화벽 확인**
```bash
# 포트가 열려있는지 확인
nc -zv 서버IP 3100
```
3. **Logseq 연결 확인**
- Logseq 앱이 실행 중인지 확인
- HTTP API가 활성화되어 있는지 확인 (설정 → API 서버)
### SSE 연결이 자주 끊기는 경우
서버의 ping 설정을 확인하세요. 기본적으로 30초마다 ping을 보냅니다.
### CORS 에러가 발생하는 경우
`MCP_CORS_ORIGINS` 환경 변수에 클라이언트 오리진을 추가하세요.
---
## 아키텍처 다이어그램
```
┌─────────────────┐ ┌─────────────────────┐ ┌─────────────┐
│ 원격 VS Code │ │ logseq-mcp 서버 │ │ Logseq │
│ │ SSE │ │ HTTP │ Desktop │
│ mcp.json 설정 │◄───────►│ HTTP/SSE 모드 │◄───────►│ │
│ type: "sse" │ │ (포트: 3100) │ │ (포트:12315)│
└─────────────────┘ └─────────────────────┘ └─────────────┘
```
---
## 빠른 시작 체크리스트
- [ ] 서버 컴퓨터에서 Logseq 실행 및 HTTP API 활성화
- [ ] `pnpm build` 실행
- [ ] 환경 변수 설정 (특히 `LOGSEQ_TOKEN`)
- [ ] `pnpm start:http:prod` 실행
- [ ] 클라이언트 VS Code에서 `.vscode/mcp.json` 설정
- [ ] VS Code 재시작 또는 MCP 연결 새로고침
