Grok-MCP

에이전트 도구 호출, 이미지 및 비디오 생성, 비전 및 파일 지원 기능을 갖춘 xAI Grok API용 MCP 서버입니다.

기능

• 에이전트 도구 호출: 다단계 추론을 통한 웹 검색, X 검색 및 코드 실행

• 다양한 Grok 모델: grok-4.20-0309-reasoning, grok-4-1-fast-reasoning 등 최신 모델에 대한 액세스

• 이미지 및 비디오 생성: Grok Imagine을 사용하여 이미지 및 비디오 생성

• 비전 기능: Grok의 비전 모델로 이미지 분석

• 파일 API: 문서 업로드, 관리 및 대화

• 상태 유지 대화: 여러 요청에 걸쳐 대화 컨텍스트를 ID로 유지

• 로컬 대화 기록: chats/ 폴더에 JSON 파일로 클라이언트 측 대화 기록을 영구 저장하는 옵션

Related MCP server: Zen MCP Server

사전 요구 사항

• Python 3.11 이상

• xAI API 키 (여기서 발급)

• Astral UV

설치

1. 저장소 복제:

git clone https://github.com/merterbak/Grok-MCP.git
cd Grok-MCP

2. 가상 환경 생성:

uv venv
source .venv/bin/activate # macOS/Linux or .venv\Scripts\activate on Windows

3. 의존성 설치:

uv sync

구성

Claude Desktop 통합

Claude Desktop 구성 파일에 다음을 추가하세요:

{
  "mcpServers": {
    "grok": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/Grok-MCP",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "XAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code 통합

프로젝트 디렉토리 내부에서 다음 명령어를 실행하세요:

claude mcp add grok-mcp -e XAI_API_KEY=your_api_key_here -- uv run --directory /path/to/Grok-MCP python main.py

또는 키가 포함된 .env 파일이 있는 경우:

 claude mcp add grok-mcp -- uv run --directory /path/to/Grok-MCP python main.py

등록되었는지 확인:

claude mcp list

Filesystem MCP (선택 사항)

Claude Desktop은 대화창에 업로드된 이미지를 MCP 도구로 보낼 수 없습니다. 컴퓨터의 파일에 직접 액세스 권한을 부여하는 가장 쉬운 방법은 공식 Filesystem MCP 서버를 사용하는 것입니다. 설정 후에는 대화창에 이미지 파일 경로(예: /Users/mert/Desktop/image.png)를 입력하기만 하면 Claude가 모든 비전 대화 도구와 함께 사용할 수 있습니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/<your-username>/Desktop",
        "/Users/<your-username>/Downloads"
      ]
    }
  }
}

stdio용:

uv run python main.py

Docker:

docker compose up --build

Mcp Inspector:

mcp dev main.py

사용 가능한 도구

각 도구는 src/server.py에 인수와 반환 형식이 포함된 전체 독스트링을 가지고 있습니다. MCP 클라이언트가 이를 직접 노출하므로, 이 목록은 사용 가능한 도구에 대한 간단한 안내입니다.

참고: 이미지와 파일을 사용하려면 대화창에 경로를 제공해야 합니다. 설정은 Filesystem MCP (선택 사항)을 참조하세요.

대화 및 추론

• chat — 선택적 영구 기록 및 다중 에이전트 지원을 포함한 표준 대화 완성.

• chat_with_vision — Grok 비전 모델로 로컬 또는 원격 이미지 분석.

• chat_with_files — 이전에 업로드된 문서를 기반으로 한 대화.

• stateful_chat — response_id를 통해 서버 측에 저장된 대화 이어가기.

• retrieve_stateful_response — ID로 저장된 응답 가져오기.

• delete_stateful_response — ID로 저장된 응답 삭제.

에이전트 도구

• web_search — 도메인 필터 및 인용을 포함한 자율 웹 조사.

• x_search — 핸들 및 날짜 필터를 포함한 X(Twitter) 게시물 자율 검색.

• code_executor — 샌드박스에서 Python을 실행하여 작업 해결.

• grok_agent — 파일, 이미지, 웹 검색, X 검색 및 코드 실행을 혼합하는 통합 에이전트.

이미지 및 비디오

• generate_image — Grok Imagine으로 이미지 생성 또는 편집 (다중 참조 편집 지원).

• generate_video — Grok Imagine으로 텍스트-비디오, 이미지-비디오 생성 또는 비디오 편집.

• extend_video — 후속 프롬프트로 기존 생성 비디오 확장.

파일

• upload_file — 로컬 문서 업로드.

• list_files — 정렬된 업로드 파일 목록 보기.

• get_file — ID로 파일 메타데이터 가져오기.

• get_file_content — 파일 내용을 텍스트로 다운로드.

• delete_file — ID로 파일 삭제.

로컬 대화 기록

• list_chat_sessions — chats/에 저장된 세션 목록 보기.

• get_chat_history — 세션의 전체 기록 가져오기.

• clear_chat_history — 세션의 로컬 기록 파일 삭제.

모델

• list_models — 실시간 가격 정보와 함께 모든 Grok 언어 및 이미지 모델 목록 보기.

라이선스

이 프로젝트는 오픈 소스이며 MIT 라이선스에 따라 제공됩니다.