de en es ja ko ru zh

grok-web-search-mcp

Name: grok-web-search-mcp
Author: NakanoSanku

by NakanoSanku

Overview Schema Related Servers Score Discussions

Python

Remote

언어: English | 中文

프로젝트 소개

에이전트는 단순한 채팅 완성(chat completion)이 아니라 인용이 포함된 실시간 웹 및 X 접근이 필요합니다. 이 프로젝트는 xAI의 서버 측 web_search 및 x_search 도구를 단일 MCP 도구로 감싸서, Grok, Cursor, Claude Desktop 같은 호스트가 xAI 클라이언트 로직을 내장하지 않고도 호출할 수 있게 합니다.

저장소: https://github.com/NakanoSanku/grok-web-search-mcp

업스트림 호출(단순화):

POST {base_url}/responses
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "model": "grok-4.5",
  "input": [{"role": "user", "content": "<query>"}],
  "tools": [
    {"type": "web_search", "enable_image_understanding": true},
    {
      "type": "x_search",
      "allowed_x_handles": ["xai"],
      "from_date": "2025-10-01",
      "to_date": "2025-10-10",
      "enable_image_understanding": true,
      "enable_video_understanding": true
    }
  ]
}

설계 목표:

하나의 MCP 도구, 하나의 호출 규약 — 모델은 query / scope / recency / images만 전달할 수 있음
간결한 결과 — query / text / citations / sources_used (원시 업스트림 덤프 없음)
커스텀 base URL — 공식 https://api.x.ai/v1 또는 OpenAI 호환 프록시
선택적 비전 입력 — https URL 또는 data URI 첨부 가능 (로컬 경로는 옵트인)
PyPI 불필요 — uvx --from git+...로 GitHub에서 직접 실행

기능

기능	비고
실시간 웹 검색	Grok이 소스 URL과 함께 답변을 종합
실시간 X 검색	기본 포함; `scope="web"` 또는 `scope="x"`로 제한 가능
X 필터	허용/차단 목록(최대 20개, `@` 제거) 및 포함 날짜 범위 처리
도메인 필터	허용 목록 또는 차단 목록(최대 5개, 상호 배타적; 스킴/경로 제거)
검색 미디어 이해	웹 페이지 및 X 게시물의 이미지; X 게시물의 동영상
클라이언트 이미지 입력	선택적 `images` (https / data URI; 로컬 경로는 옵트인)
간결한 JSON 출력	도구 결과에 `model` / `base_url` / annotations / 원시 페이로드 없음
프로토콜 오류	업스트림/검증 실패 시 MCP `isError` 설정 (가짜 `ok: false` 페이로드 아님)
재시도	429 / 502 / 503 / 504 및 전송 타임아웃, 백오프 포함
프록시 친화적	`GROK_BASE_URL` / `XAI_BASE_URL`
GitHub 설치	`uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git`

미포함: enable_image_search (웹 이미지 갤러리 임베딩). 사용자가 이미지를 제공할 때는 images를 사용하고, 탐색한 페이지 및 X 게시물의 이미지에는 enable_image_understanding을 사용하세요.

사용된 기술

Related MCP server: WebQuest MCP

시작하기

사전 요구사항

Python 3.10+
xAI API 키 (또는 호환 게이트웨이용 키)
uv (GitHub에서 uvx 사용 시 권장)

# optional: install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

빠른 시작 (GitHub에서 uvx)

일상적인 MCP 사용에는 로컬 클론이 필요 없습니다:

export GROK_API_KEY=xai-...
uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git grok-web-search-mcp

재현성이 필요할 때는 브랜치, 태그 또는 커밋을 고정하세요:

uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git@main grok-web-search-mcp
# uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git@v0.3.0 grok-web-search-mcp

로컬 개발 설치

저장소를 클론합니다:

git clone https://github.com/NakanoSanku/grok-web-search-mcp.git
cd grok-web-search-mcp

의존성을 설치합니다:
```
uv sync
# or: pip install -e ".[dev]"
```
로컬 env 파일을 생성합니다:
```
cp .env.example .env
```
.env를 편집하고 최소한 GROK_API_KEY를 설정합니다 (설정 참조).

설정

변수	필수	기본값	설명
`GROK_API_KEY`	예	—	`XAI_API_KEY` / `GROK_WEB_SEARCH_API_KEY`도 허용
`GROK_BASE_URL`	아니요	`https://api.x.ai/v1`	`XAI_BASE_URL` / `GROK_WEB_SEARCH_BASE_URL`도 허용
`GROK_MODEL`	아니요	`grok-4.5`	`XAI_MODEL`도 허용
`GROK_TIMEOUT`	아니요	`300`	요청 타임아웃(초, 1–3600). 높은 추론 + 검색은 수 분이 걸릴 수 있음
`GROK_CONNECT_TIMEOUT`	아니요	`15`	TCP/TLS 연결 타임아웃 (`GROK_TIMEOUT`에 의해 상한 제한)
`GROK_ENABLE_IMAGE_UNDERSTANDING`	아니요	`true`	탐색한 페이지 및 X 게시물의 이미지 분석
`GROK_REASONING_EFFORT`	아니요	`low`	기본 추론 길이: `low` / `medium` / `high`; `XAI_REASONING_EFFORT`도 허용
`GROK_ALLOW_LOCAL_IMAGES`	아니요	`false`	`images`가 로컬 파일을 읽도록 허용 (cwd / `GROK_LOCAL_IMAGE_ROOT`로 제한)
`GROK_LOCAL_IMAGE_ROOT`	아니요	cwd	활성화 시 로컬 이미지용 디렉터리 격리(jail)
`GROK_MAX_RETRIES`	아니요	`3`	429/5xx/타임아웃 재시도 횟수 (0–8)
`GROK_LOG_LEVEL`	아니요	`INFO`	`DEBUG` / `INFO` / `WARNING` / `ERROR`
`GROK_ENABLE_VIDEO_UNDERSTANDING`	아니요	`false`	X 게시물의 동영상 분석 (운영자 전용; 도구 인자가 아님)
`GROK_ALLOWED_DOMAINS`	아니요	—	운영자 웹 허용 목록 (최대 5개). 호출자는 설정할 수 없음
`GROK_EXCLUDED_DOMAINS`	아니요	—	운영자 웹 차단 목록 (최대 5개)
`GROK_ALLOWED_X_HANDLES`	아니요	—	운영자 X 핸들 허용 목록 (최대 20개)
`GROK_EXCLUDED_X_HANDLES`	아니요	—	운영자 X 핸들 차단 목록 (최대 20개)
`GROK_SEARCH_INSTRUCTIONS`	아니요	—	서버 소유 시스템 프롬프트에 추가되는 추가 규칙

비밀값을 git에 커밋하지 마세요. 가능하면 MCP 설정에는 호스트가 주입한 env를 사용하세요.

사용법

서버 실행

권장 (GitHub에서):

export GROK_API_KEY=xai-...
uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git grok-web-search-mcp

로컬 체크아웃에서:

export GROK_API_KEY=xai-...
# Windows PowerShell: $env:GROK_API_KEY="xai-..."

uv run grok-web-search-mcp
# or
uv run python -m grok_web_search_mcp

호환 프록시 예시:

export GROK_API_KEY=sk-xxx
export GROK_BASE_URL=http://127.0.0.1:8317/v1
export GROK_MODEL=grok-4.5
uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git grok-web-search-mcp

MCP 호스트 설정

권장: uvx로 GitHub에서 실행 (로컬 경로 불필요).

JSON 스타일 호스트 (Cursor / Claude Desktop 등):

{
  "mcpServers": {
    "grok-web-search": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NakanoSanku/grok-web-search-mcp.git",
        "grok-web-search-mcp"
      ],
      "env": {
        "GROK_API_KEY": "xai-your-key",
        "GROK_BASE_URL": "https://api.x.ai/v1",
        "GROK_MODEL": "grok-4.5"
      }
    }
  }
}

Grok 사용자 설정 (~/.grok/config.toml):

[mcp_servers.grok-web-search]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/NakanoSanku/grok-web-search-mcp.git",
  "grok-web-search-mcp",
]
enabled = true

[mcp_servers.grok-web-search.env]
GROK_API_KEY = "xai-your-key"
GROK_BASE_URL = "https://api.x.ai/v1"
GROK_MODEL = "grok-4.5"

ref 고정 (브랜치 / 태그 / 커밋):

args = [
  "--from",
  "git+https://github.com/NakanoSanku/grok-web-search-mcp.git@main",
  "grok-web-search-mcp",
]

로컬 개발 전용 (체크아웃의 절대 경로):

[mcp_servers.grok-web-search]
command = "uv"
args = [
  "run",
  "--directory",
  "/absolute/path/to/grok-web-search-mcp",
  "grok-web-search-mcp",
]
enabled = true

도구: `web_search`

모든 호스트 모델은 동일한 4키 계약을 사용해야 합니다. 추가 인자(model, reasoning_effort, system_prompt, 도메인/핸들 필터)는 거부됩니다. 품질 조정은 환경 변수에 있으므로 검색 동작이 모델 간에 달라지지 않습니다.

매개변수	유형	설명
`query`	string	필수. 자연어 질문, 2–600자. 키워드 목록(`xAI Grok valuation`)이나 채팅 기록이 아님. 키워드 묶음은 서버 측에서 재작성됩니다.
`scope`	`"all"` \| `"web"` \| `"x"`	기본값 `all` (웹 + X). 일반 사실에는 `web`, 게시물/계정 전용에는 `x`를 사용하세요.
`recency`	`"any"` \| `"day"` \| `"week"` \| `"month"` \| `"year"`	기본값 `any`. 사용자가 시간 범위를 요청한 경우에만 설정하세요.
`images`	string[]?	선택적 이미지 URL (http(s) / data URI, 최대 5개). 사용자가 이미지를 제공한 경우에만 사용하세요.

표준 예시:

{ "query": "What is xAI's latest valuation?" }

그런 다음 서버는: query를 정규화하고, 고정 시스템 프롬프트를 주입하고, env에서 운영자 필터를 적용하고, recency를 X 날짜 범위로 매핑하며, 항상 설정된 모델 / 추론 수준을 사용합니다.

images는 Responses API input_image 파트입니다. 로컬 파일시스템 경로는 기본적으로 비활성화되어 있습니다. 이는 "스톡 이미지를 웹에서 검색"하는 기능이 아닙니다.

응답 형태

성공(MCP isError: false, 구조화된 콘텐츠):

{
  "query": "What is xAI?",
  "text": "...",
  "citations": [{"url": "https://x.ai", "title": "xAI"}],
  "sources_used": ["web", "x"],
  "scope": "all",
  "recency": "any"
}

실패는 짧은 메시지와 함께 프로토콜 수준 도구 오류(isError: true)입니다(예: Grok API error (401): Invalid API key). 불완전하거나 빈 업스트림 응답도 오류로 처리되며, 조용한 성공으로 간주되지 않습니다.

의도적으로 반환하지 않는 항목: API 키, model, base_url, 원시 업스트림 JSON 또는 주석 블롭(URL은 citations로만 추출됩니다). 도구 결과 외부(env / 호스트 MCP 설정 / stderr 로그)에서 구성을 진단하세요.

Python 클라이언트 예제

import asyncio
from grok_web_search_mcp.client import GrokWebSearchClient
from grok_web_search_mcp.config import Settings

async def main():
    async with GrokWebSearchClient(Settings.from_env()) as client:
        result = await client.web_search("What is xAI?")
        print(result.to_dict())

asyncio.run(main())

실제 호출은 모델 및 서버 측 검색 할당량을 소비합니다. 단위 테스트는 목(mock)을 사용하며 네트워크에 접속하지 않습니다.

개발

git clone https://github.com/NakanoSanku/grok-web-search-mcp.git
cd grok-web-search-mcp
uv sync --extra dev
uv run pytest
# live API (optional): GROK_LIVE=1 uv run pytest -m live

프로젝트 구조:

src/grok_web_search_mcp/
  server.py    # MCP tool surface
  client.py    # Responses API client + image helpers
  config.py    # Environment settings
tests/

로드맵

단일 경량 web_search MCP 도구
기본적으로 업스트림 web_search 및 x_search 활성화
X 핸들/날짜 필터 및 이미지/비디오 이해
사용자 지정 base_url / 프록시 지원
도메인 허용/차단 필터
선택적 멀티모달 이미지 입력
uvx를 통한 GitHub 설치/실행
프로토콜 수준 오류, 재시도, 타임아웃/추론 기본값
로컬 이미지 격리(기본적으로 비활성화)
표준 MCP 호출 계약(query / scope / recency / images)
선택적 Streamable HTTP 전송 문서/예제
검색 품질을 위한 골든 세트 평가 하네스

오픈 이슈를 참조하세요.

기여

기여를 환영합니다.

프로젝트를 포크하세요
기능 브랜치를 생성하세요 (git checkout -b feature/AmazingFeature)
변경 사항을 커밋하세요 (git commit -m 'Add some AmazingFeature')
브랜치에 푸시하세요 (git push origin feature/AmazingFeature)
풀 리퀘스트를 여세요

도구 표면을 간결하게 유지하세요: 많은 얇은 래퍼보다 잘 문서화된 단일 도구를 선호하세요.

라이선스

MIT 라이선스에 따라 배포됩니다. 자세한 내용은 LICENSE를 참조하세요.

감사의 말

Available Tools

1 tool

web_searchA

Live web and X search via Grok. Returns ok, text (answer), citations (URL list). Optional images: public URL, data:image/...;base64,..., or local file path (max 5) to ask about a picture while searching. Supports web domain filters, X handle/date filters, and reasoning_effort (low/medium/high). Image understanding applies to browsed pages and X posts; video understanding applies to X posts only.

ParametersJSON Schema

Name	Required	Description
`model`	No	Optional model override (default from GROK_MODEL / grok-4.5).
`query`	Yes	Natural-language search question or topic.
`images`	No	Optional image input(s) for visual questions: URL / data-URI / local path (comma or newline separated, max 5). Not an image-search API.
`to_date`	No	Optional inclusive X search end date (YYYY-MM-DD).
`from_date`	No	Optional inclusive X search start date (YYYY-MM-DD).
`image_detail`	No	Vision detail for input images: low \| high \| auto (default high).
`system_prompt`	No	Optional system instruction prepended to the request.
`allowed_domains`	No	Optional comma-separated allowlist (max 5). Mutually exclusive with excluded_domains.
`excluded_domains`	No	Optional comma-separated denylist (max 5).
`reasoning_effort`	No	Optional thinking length for reasoning models: low \| medium \| high.
`allowed_x_handles`	No	Optional comma-separated X handle allowlist (max 20). Mutually exclusive with excluded_x_handles.
`excluded_x_handles`	No	Optional comma-separated X handle denylist (max 20).
`enable_image_understanding`	No	Analyze images found on browsed pages and X posts (default on).
`enable_video_understanding`	No	Analyze videos found in X posts (default off).

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses return format, image handling constraints (max 5, types), and scoping of image/video understanding. It lacks explicit mention of read-only nature but is otherwise transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (6 sentences), front-loaded with core purpose, and every sentence adds meaningful information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (14 parameters, optional features) and the presence of an output schema, the description covers most behavioral aspects. Minor gaps exist (e.g., rate limits, indexing scope), but overall it is thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by summarizing key parameters (domain filters, reasoning_effort) and clarifying behavior of image/video understanding fields, which are not detailed in schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it performs 'Live web and X search via Grok' and details return values. It uses a specific verb (search) and resource (web and X), and the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While no sibling tools exist for comparison, the description provides clear context on features and filters, sufficiently guiding usage. It could benefit from explicit when-not-to-use, but the absence of alternatives makes this less critical.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

1 tool updatev0.1.0Jul 28, 2026
- First observedweb_search

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0

Disambiguation5/5

Only one tool exists, so there is no possibility of confusion or overlap with other tools.

Naming Consistency5/5

With a single tool, naming consistency is inherently perfect as there is no pattern to break.

Tool Count4/5

A single tool is slightly minimal but reasonably scoped for a focused web search server, as the tool itself is comprehensive.

Completeness5/5

The tool covers web search, X search, image understanding, domain and date filters, and reasoning effort, leaving no obvious gaps for its stated purpose.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

pixserp A
com.pixserp
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Search Browser Automation
12
Keenable Web Search A
ai.keenable.api
Docs: https://docs.keenable.ai/mcp-server Keenable is a free, remote MCP server that gives agents access to the web index. Search the web with ranked results and date/site filters, then fetch any indexed page as clean markdown. Works out of the box with no account or API key.
Research & Data Search Web Scraping
23
mcp A
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102
MESSORA A
dev.messora
Scrape, crawl and search the web for AI agents via MCP.
Web Scraping Browser Automation Search
51

Related MCP Servers

xai-search-mcp
Search Social Media
kicito
A
license
A
quality
D
maintenance
An MCP server that provides real-time web search and X (Twitter) search capabilities via the xAI API.
Updated 5 months ago (2026-04-22 12:57 UTC)
2
28
MIT
WebQuest MCP
Browser Automation Web Scraping
mustafametesengul
A
license
Not graded
quality
C
maintenance
A Model Context Protocol server that exposes powerful web search and scraping tools to AI agents and MCP-compatible clients.
Updated 7 months ago (2026-02-12 20:56 UTC)
Apache 2.0
bluex-mcp
Search Social Media
Derek-Wong213
A
license
A
quality
B
maintenance
MCP server for live X/Twitter and web search, driven by your locally logged-in Grok CLI and leveraging your X Premium or SuperGrok subscription quota.
Updated 2 months ago (2026-06-30 16:31 UTC)
3
1
MIT
grok-mcp
Search Web Scraping Social Media
dq52099
F
license
Not graded
quality
C
maintenance
MCP server providing web search, news search, and X/Twitter search capabilities via HTTP or stdio.
Updated a month ago (2026-07-26 22:44 UTC)
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/NakanoSanku/grok-web-search-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

프로젝트 소개

기능

사용된 기술

시작하기

사전 요구사항

빠른 시작 (GitHub에서 uvx)

로컬 개발 설치

설정

사용법

서버 실행

MCP 호스트 설정

도구: web_search

응답 형태

Python 클라이언트 예제

개발

로드맵

기여

라이선스

감사의 말

Available Tools

Output Schema

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

xai-search-mcp

WebQuest MCP

bluex-mcp

grok-mcp

Latest Blog Posts

MCP directory API

도구: `web_search`