마블 MCP 서버

기능 • 도구 • 설정 • MCP 호스트 구성

Marvel Developer API 용 MCP 서버로, 캐릭터 및 만화 데이터와의 상호작용을 지원합니다. 이 프로젝트의 주요 목표는 MCP 서버를 사용하여 API와 상호작용하는 방법을 보여주는 것입니다.

참고 : 이 MCP 서버에서 사용하는 모든 데이터는 공식 Marvel API 에서 가져오며 Marvel의 소유입니다. 이 프로젝트는 Marvel과 어떠한 제휴 관계도 없습니다.

🔧 특징

• 마블 캐릭터 목록 : nameStartsWith , limit , comics , series 등의 필터를 지원합니다.
• ID로 Marvel 캐릭터 가져오기 : characterId 사용하여 모든 캐릭터에 대한 자세한 정보를 가져옵니다.
• 특정 캐릭터의 만화 가져오기 : format , dateRange 등 다양한 필터를 적용하여 특정 캐릭터가 등장하는 만화 목록을 가져옵니다.
• 도구 기반 MCP 통합 : 이 서버를 MCP(Model Context Protocol) 도구(VS Code, Claude 등)에 등록합니다.
• 환경 구성 : .env 파일을 사용하여 MARVEL_PUBLIC_KEY , MARVEL_PRIVATE_KEY 및 MARVEL_API_BASE 와 같은 환경 변수를 관리합니다.

🧰 도구

1. get_characters 🔍🦸‍♂️

• 설명 : 선택적 필터를 적용하여 Marvel 캐릭터를 가져옵니다.
• 입력 :
  • name (선택적 문자열): 전체 캐릭터 이름.
  • nameStartsWith (선택적 문자열): 지정된 문자열로 시작하는 이름을 가진 문자입니다.
  • modifiedSince (선택적 문자열): 이 날짜 이후 수정된 문자를 필터링하기 위한 ISO 8601 날짜 문자열입니다.
  • comics , series , events , stories (선택적 문자열): 관련 엔터티로 필터링할 ID의 쉼표로 구분된 목록입니다.
  • orderBy (선택적 문자열): name 또는 -modified 등 결과를 정렬할 필드입니다.
  • limit (선택적 숫자): 반환할 결과의 최대 개수(1~100).
  • offset (선택적 숫자): 페이지 나누기를 위해 건너뛸 결과의 수입니다.
• 반환 : 일치하는 문자가 포함된 JSON 응답입니다. 자세한 내용은 src/schemas.ts 의 CharacterDataWrapperSchema 참조하세요.

2. get_character_by_id 🆔🧑‍🎤

• 설명 : 고유 ID로 Marvel 캐릭터를 가져옵니다.
• 입력 :
  • characterId (숫자): 캐릭터의 고유 ID입니다.
• 반환 : 캐릭터 세부 정보가 포함된 JSON 응답입니다. 자세한 내용은 src/schemas.ts 의 CharacterDataWrapperSchema 참조하세요.

3. get_comics_for_character 📚🎭

• 설명 : 특정 캐릭터가 등장하는 만화를 가져오며, 선택적인 필터도 적용 가능합니다.
• 입력 :
  • characterId (숫자): 캐릭터의 고유 ID입니다.
  • 선택 필터:
    • format , formatType (문자열): 만화 형식(예: comic , hardcover )으로 필터링합니다.
    • noVariants , hasDigitalIssue (부울): 변형을 제외할지 또는 디지털 이슈만 포함할지 여부를 나타내는 플래그입니다.
    • dateDescriptor (문자열): thisWeek , nextWeek 와 같은 미리 정의된 날짜 범위.
    • dateRange (문자열): YYYY-MM-DD,YYYY-MM-DD 형식의 사용자 지정 날짜 범위.
    • title , titleStartsWith (문자열): 제목 또는 제목 접두사로 필터링합니다.
    • startYear , issueNumber , digitalId (숫자): 숫자 필터.
    • diamondCode , upc , isbn , ean , issn (문자열): 식별자 필터.
    • creators , series , events , stories , sharedAppearances , collaborators (문자열): 관련 엔터티 ID의 쉼표로 구분된 목록입니다.
    • orderBy (문자열): title 이나 -modified 등 결과를 정렬할 필드입니다.
    • limit , offset (숫자): 페이지 번호 옵션.
• 반환값 : 지정된 캐릭터가 등장하는 만화를 JSON으로 반환합니다. 자세한 내용은 src/schemas.ts 의 ComicDataWrapperSchema 참조하세요.

4. get_comics 📖🕵️‍♂️

• 설명 : 선택적 필터를 적용한 Marvel 만화 목록을 가져옵니다.
• 입력 :
  • format (선택적 문자열): 문제 형식(예: comic , digital comic , hardcover )으로 필터링합니다.
  • formatType (선택적 문자열): 이슈 포맷 유형( comic 또는 collection )으로 필터링합니다.
  • noVariants (선택적 부울): 결과 집합에서 변형(대체 표지, 2차 인쇄, 감독판 등)을 제외합니다.
  • dateDescriptor (선택적 문자열): 미리 정의된 날짜 범위( lastWeek , thisWeek , nextWeek , thisMonth ) 내의 만화를 반환합니다.
  • dateRange (선택 문자열): 사용자 지정 날짜 범위 내의 만화를 반환합니다. 날짜는 YYYY-MM-DD,YYYY-MM-DD 형식으로 지정해야 합니다.
  • title (선택적 문자열): 제목이 입력과 일치하는 시리즈의 이슈만 반환합니다.
  • titleStartsWith (선택적 문자열): 제목이 입력으로 시작하는 시리즈의 문제만 반환합니다.
  • startYear (선택적 숫자): 입력과 일치하는 시작 연도를 가진 시리즈의 문제만 반환합니다.
  • issueNumber (선택적 숫자): 입력과 일치하는 이슈 번호가 있는 시리즈의 이슈만 반환합니다.
  • diamondCode , digitalId , upc , isbn , ean , issn (선택 문자열): 다양한 식별자로 필터링합니다.
  • hasDigitalIssue (선택적 부울): 디지털로 제공되는 결과만 포함합니다.
  • modifiedSince (선택적 문자열): 지정된 날짜 이후에 수정된 만화만 반환합니다(ISO 8601 형식).
  • creators , characters , series , events , stories , sharedAppearances , collaborators (선택적 문자열): 관련 엔터티로 필터링할 ID의 쉼표로 구분된 목록입니다.
  • orderBy (선택 문자열): 결과 집합을 필드별로 정렬합니다. 내림차순으로 정렬하려면 값에 "-"를 추가합니다(예: title , -modified ).
  • limit (선택적 숫자): 결과 집합을 지정된 리소스 수로 제한합니다(기본값: 20, 최대값: 100).
  • offset (선택적 숫자): 결과 집합에서 지정된 수의 리소스를 건너뜁니다.
• 반환 : 일치하는 만화가 포함된 JSON 응답입니다. 자세한 내용은 src/schemas.ts 의 ComicDataWrapperSchema 참조하세요.

5. get_comic_by_id 🆔📘

• 설명 : 고유 ID로 Marvel 만화책 한 권을 가져옵니다.
• 입력 :
  • comicId (숫자): 만화의 고유 ID입니다.
• 반환값 : 만화 세부 정보가 포함된 JSON 응답입니다. 자세한 내용은 src/schemas.ts 의 ComicDataWrapperSchema 참조하세요.

6. get_characters_for_comic 🦸‍♀️📖

• 설명 : 특정 만화에 등장하는 Marvel 캐릭터를 가져옵니다.
• 입력 :
  • comicId (숫자): 만화의 고유 ID입니다.
  • 선택 필터:
    • name (선택적 문자열): 전체 이름으로 문자를 필터링합니다.
    • nameStartsWith (선택적 문자열): 지정된 문자열로 시작하는 이름의 문자를 필터링합니다.
    • modifiedSince (선택적 문자열): 이 날짜 이후 수정된 문자를 필터링하기 위한 ISO 8601 날짜 문자열입니다.
    • series , events , stories (선택적 문자열): 필터링 기준으로 사용할 관련 엔터티 ID의 쉼표로 구분된 목록입니다.
    • orderBy (선택적 문자열): name 또는 -modified 등 결과를 정렬할 필드입니다.
    • limit (선택적 숫자): 반환할 결과의 최대 개수(1~100).
    • offset (선택적 숫자): 페이지 나누기를 위해 건너뛸 결과의 수입니다.
• 반환값 : 지정된 만화에 등장하는 캐릭터가 포함된 JSON 응답입니다. 자세한 내용은 src/schemas.ts 의 CharacterDataWrapperSchema 참조하세요.

🛠️ 설정

Marvel Developer API 계정에 가입하고 공개 및 비공개 API 키를 받으세요.

MCP 호스트에서 직접 실행하려면 Claude Desktop과 함께 사용 또는 GitHub Copilot과 함께 사용 섹션으로 이동하세요.

MCP Inspector를 사용하여 로컬로 서버 실행

서버를 테스트하기 위해 MCP Inspector를 로컬로 실행하려면 다음 단계를 따르세요.

1. 이 저장소를 복제하세요:지엑스피1
2. .env.template``.env 로 이름을 바꾸세요.
3. Marvel API 공개 키와 개인 키를 .env 파일에 추가합니다.
   MARVEL_PUBLIC_KEY=YOUR_PUBLIC_KEY MARVEL_PRIVATE_KEY=YOUR_PRIVATE_KEY MARVEL_API_BASE=https://gateway.marvel.com/v1/public
4. 필요한 종속성을 설치하고 프로젝트를 빌드합니다.
   npm install npm run build
5. (선택 사항) MCP Inspector를 사용하여 서버를 시험해 보려면 다음 명령을 실행하세요.
   # Start the MCP Inspector npx @modelcontextprotocol/inspector node build/index.js
   브라우저 콘솔에 표시된 MCP Inspector URL로 이동합니다. Arguments``dist/index.js 로 변경하고 Connect 선택합니다. List Tools 선택하면 사용 가능한 도구가 표시됩니다.

MCP 호스트 구성

Claude Desktop과 함께 사용

claude_desktop_config.json 에 다음을 추가하세요.

Smithery를 통해 설치

Smithery를 통해 Claude Desktop에 Marvel MCP Server를 자동으로 설치하려면:

GitHub Copilot(VS Code Insiders)과 함께 사용

참고 : Claude Desktop에서 MCP 서버를 이미 활성화한 경우 VS Code 설정에 chat.mcp.discovery.enabled: true 추가하면 기존 MCP 서버 목록을 검색합니다.

MCP 서버를 특정 리포지토리와 연결하려면 다음 내용이 포함된 .vscode/mcp.json 파일을 만드세요.

MCP 서버를 모든 저장소와 연결하려면 VS Code 사용자 설정 JSON에 다음을 추가하세요.

GitHub Copilot의 도구 사용

1. 이제 mcp 서버를 검색할 수 있으므로 GitHub Copilot을 열고 Agent 모드( Chat 이나 Edits 아님)를 선택합니다.
2. Copilot 채팅 텍스트 필드에서 "새로 고침" 버튼을 선택하여 서버 목록을 새로 고칩니다.
3. 이 저장소의 도구를 포함하여 가능한 모든 도구를 보려면 "🛠️" 버튼을 선택하세요.
4. 예를 들어, 다음과 같이 도구 중 하나를 자연스럽게 불러올 질문을 채팅에 입력하세요.
   List 10 marvel characters. Include images. What comics is Wolverine in? Which characters appear in the Avengers comics? What characters are in the Hedge Knight II: Sworn Sword (2007) comic?

   참고 : "죄송합니다. 응답은 Responsible AI Service에서 필터링되었습니다."라는 메시지가 표시되면 다시 실행하거나 메시지를 다시 작성해 보세요.