서버실행.md•5.06 kB
# 🚀 MCP 서버 로컬 실행 가이드
Cursor AI IDE에서 사용할 수 있는 **Markdown 문서 관리 MCP 서버**를 로컬에서 실행하고 사용하는 방법을 안내합니다.
## 📋 목차
- [1. 서버 실행](#1-서버-실행)
- [2. IDE 설정](#2-ide-설정)
- [3. 사용 방법](#3-사용-방법)
- [4. 자동 실행 설정](#4-자동-실행-설정)
- [5. 문제 해결](#5-문제-해결)
- [6. 실사용 예시](#6-실사용-예시)
---
## 1. 서버 실행
### 1.1 기본 실행 방법
터미널에서 아래 명령어를 실행하세요:
```bash
cd /Users/gukho/Desktop/git/mcp_python
python -m src.server
```
### 1.2 실행 확인
정상적으로 실행되면 아래와 같은 로그가 출력됩니다:
```
INFO - MarkdownManager initialized with base path: /Users/gukho/Desktop/git/mcp_python
INFO - Markdown MCP Server initialized
INFO - Starting Markdown MCP Server...
```
### 1.3 서버 중지
서버를 중지하려면 터미널에서 **Ctrl+C**를 누르세요.
---
## 2. IDE 설정
### 2.1 Cursor AI IDE 설정
`cursor-settings.json` 파일에 아래 설정을 추가하세요:
```json
{
"mcp": {
"servers": {
"markdown-manager": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "/Users/gukho/Desktop/git/mcp_python"
}
}
}
}
```
### 2.2 설정 확인
- `cwd` 경로가 MCP 서버 코드가 있는 폴더인지 확인
- IDE를 재시작하여 설정을 적용
---
## 3. 사용 방법
### 3.1 기본 사용법
IDE에서 자연어로 명령을 내리면 자동으로 MCP 서버가 동작합니다.
### 3.2 사용 가능한 명령들
| 기능 | 명령 예시 |
|------|-----------|
| 📝 문서 생성 | "새로운 프로젝트 문서를 생성해주세요" |
| 📖 문서 읽기 | "README.md 파일을 읽어줘" |
| 🔍 문서 검색 | "API 키워드가 포함된 문서를 찾아줘" |
| ✏️ 문서 수정 | "README.md에 설치 가이드를 추가해줘" |
| 📋 문서 목록 | "현재 디렉토리의 마크다운 파일들을 보여줘" |
| 🗑️ 문서 삭제 | "test.md 파일을 삭제해줘" |
---
## 4. 자동 실행 설정
### 4.1 VSCode 터미널 자동 실행
`.vscode/settings.json` 파일에 추가:
```json
{
"terminal.integrated.profiles.osx": {
"MCP Server": {
"path": "python",
"args": ["-m", "src.server"],
"cwd": "/Users/gukho/Desktop/git/mcp_python"
}
}
}
```
### 4.2 macOS 단축어 설정
1. **단축어 앱** 열기
2. **새로운 단축어** 생성
3. **스크립트 실행** 액션 추가:
```bash
cd /Users/gukho/Desktop/git/mcp_python && python -m src.server
```
4. **단축키** 설정 (예: Cmd+Shift+M)
### 4.3 Bash/Zsh Profile 설정
`~/.zshrc` 또는 `~/.bash_profile`에 추가:
```bash
# MCP 서버 실행 함수
mcp-server() {
cd /Users/gukho/Desktop/git/mcp_python
python -m src.server
}
# 별칭 설정
alias mcp='mcp-server'
```
---
## 5. 문제 해결
### 5.1 서버가 실행되지 않는 경우
1. **Python 버전 확인**
```bash
python --version # Python 3.9+ 필요
```
2. **의존성 설치 확인**
```bash
pip install -r requirements.txt
```
3. **경로 확인**
```bash
ls -la /Users/gukho/Desktop/git/mcp_python/src/server.py
```
### 5.2 IDE에서 명령이 동작하지 않는 경우
1. **서버 실행 상태 확인**
- 터미널에 서버 로그가 출력되는지 확인
2. **IDE 설정 확인**
- `cursor-settings.json` 경로가 올바른지 확인
- IDE 재시작
3. **로그 확인**
- 터미널에 에러 메시지가 있는지 확인
### 5.3 일반적인 에러
| 에러 | 해결 방법 |
|------|-----------|
| `ModuleNotFoundError` | `pip install -r requirements.txt` 실행 |
| `Permission denied` | 파일 권한 확인 및 수정 |
| `File not found` | 경로 설정 확인 |
---
## 6. 실사용 예시
### 6.1 기본 워크플로우
1. **서버 실행**
```bash
python -m src.server
```
2. **IDE에서 명령 실행**
```
"새로운 프로젝트 문서를 생성해주세요. 파일명: project-overview.md"
```
3. **결과 확인**
- 파일이 생성되고 IDE에서 내용 편집 가능
### 6.2 고급 사용 예시
| 시나리오 | 명령 |
|----------|------|
| 문서 생성 → 내용 추가 | "project.md 파일에 프로젝트 목표를 추가해줘" |
| 문서 검색 → 수정 | "API 문서를 찾아서 버전 정보를 업데이트해줘" |
| 메타데이터 관리 | "README.md의 frontmatter에 author 정보를 추가해줘" |
---
## 🎯 요약
1. **터미널에서 서버 실행**: `python -m src.server`
2. **IDE 설정**: `cursor-settings.json`에 MCP 서버 등록
3. **자연어 명령**: IDE에서 자연어로 문서 관리
4. **자동화**: 필요시 자동 실행 설정
---
## 📞 지원
문제가 발생하거나 궁금한 점이 있으시면:
- 터미널 에러 로그 확인
- IDE 설정 재확인
- 추가 질문 시 에러 메시지와 함께 문의
---
**Happy Document Management! 📚✨**