📝 Sample MCP Server

company-info-mcp 구조를 기반으로 한 샘플 MCP 서버입니다.

이 프로젝트는 다른 MCP 프로젝트를 만들 때 참고할 수 있는 템플릿입니다.

✨ 주요 기능

• 랜덤 명언 조회: 무료 Quote API를 사용하여 랜덤 명언 가져오기

• 명언 검색: 키워드로 명언 검색

• ID로 조회: 특정 ID의 명언 조회

🛠️ 기술 스택

• MCP Framework: FastMCP

• HTTP Server: FastAPI

• Data Validation: Pydantic

• HTTP Client: Requests

• Caching: cachetools (TTL 캐시)

• Environment: Python-dotenv

📦 설치 및 설정

1) 의존성 설치

pip install -r requirements.txt

2) 환경 변수 설정 (선택)

프로젝트 루트에 .env 파일을 생성:

cp env.example .env

.env 파일 내용:

LOG_LEVEL=INFO
PORT=8098

💡 이 예제는 무료 API를 사용하므로 API 키가 필요 없습니다.

3) 서버 실행

MCP 서버 모드 (stdio)

python -m src.main

HTTP 서버 모드

HTTP_MODE=1 python -m src.main

HTTP 서버는 기본적으로 http://localhost:8098에서 실행됩니다.

🔌 MCP 클라이언트 설정

Claude Desktop

claude_desktop_config.json 파일에 다음을 추가:

설정 파일 위치:

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

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

설정 예시:

{
  "mcpServers": {
    "sample-quote": {
      "command": "python",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/sample-mcp-server",
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

🧰 사용 가능한 MCP 도구

health

서비스 상태 확인

get_random_quote_tool

랜덤 명언을 조회합니다.

search_quotes_tool

키워드로 명언을 검색합니다.

파라미터:

• keyword (필수): 검색할 키워드

• limit (선택): 결과 개수 (기본값: 10, 최대: 50)

get_quote_by_id_tool

ID로 특정 명언을 조회합니다.

파라미터:

• quote_id (필수): 인용구 ID

📡 HTTP API 엔드포인트

HTTP 모드로 실행 시 다음 엔드포인트를 사용할 수 있습니다:

Health Check

GET /health
POST /health

도구 목록 조회

GET /tools

도구 실행

POST /tools/{tool_name}
Content-Type: application/json

{
  "keyword": "success",
  "limit": 5,
  "env": {
    "QUOTE_API_KEY": "your_api_key"
  }
}

🏗️ 프로젝트 구조

sample-mcp-server/
├── src/
│   ├── __init__.py
│   ├── main.py          # FastMCP 서버 + FastAPI HTTP 엔드포인트
│   └── tools.py          # 실제 API 호출 로직
├── requirements.txt
├── pyproject.toml
├── env.example
└── README.md

📚 이 프로젝트를 참고하여 새 MCP 만들기

1. 이 프로젝트를 복사하여 새 프로젝트 생성

2. src/main.py에서 도구 정의 수정

3. src/tools.py에서 실제 API 호출 로직 구현

4. pyproject.toml에서 프로젝트명 변경

5. requirements.txt에 필요한 의존성 추가

6. env.example에 필요한 환경 변수 추가

🔑 API 키 우선순위

MCP 서버는 다음 순서로 API 키를 찾습니다:

1. 우선순위 1: arguments.env.QUOTE_API_KEY (메인 서버에서 받은 키)

2. 우선순위 2: .env 파일의 QUOTE_API_KEY (로컬 개발용)

📄 라이선스

MIT License

이 프로젝트는 MCP 서버 개발 템플릿입니다.