mcp-research

웹 조사, 학술 논문, Twitter/X, YouTube 및 파일 수집을 위한 MCP 서버입니다. AI 어시스턴트를 위한 8가지 도구를 모두 MCP stdio 프로토콜을 통해 제공합니다. 기관 접근을 위한 자격 증명 보관소, CAPTCHA 감지 및 토큰 효율적인 출력을 포함합니다.

도구

모든 도구는 읽기 전용입니다. 콘텐츠를 가져오고 변환할 뿐, 절대 수정하지 않습니다.

Related MCP server: Research Powerpack MCP

설치

pip install mcp-research

또는 uvx를 사용하여 직접 실행 (설치 불필요):

uvx mcp-research

선택적 추가 기능:

pip install 'mcp-research[twitter]' # yt-dlp for Twitter extraction
pip install 'mcp-research[youtube]' # yt-dlp + faster-whisper for YouTube
pip install 'mcp-research[academic]' # PyPDF2 for academic PDFs
pip install 'mcp-research[ingest]' # PDF, DOCX, XLSX, PPTX, audio support
pip install 'mcp-research[all]' # everything

설정 확인:

mcp-research doctor

Claude Code와 함께 사용

Claude Code MCP 설정(~/.claude/settings.json 또는 프로젝트 .mcp.json)에 추가하세요:

{
 "mcpServers": {
 "research": {
 "command": "uvx",
 "args": ["mcp-research"],
 "env": {
 "BRAVE_API_KEY": "BSA...",
 "OLLAMA_URL": "http://localhost:11434"
 }
 }
 }
}

Claude Desktop과 함께 사용

claude_desktop_config.json에 추가하세요:

{
 "mcpServers": {
 "research": {
 "command": "uvx",
 "args": ["mcp-research"],
 "env": {
 "BRAVE_API_KEY": "BSA..."
 }
 }
 }
}

구성

모든 구성은 환경 변수를 통해 이루어지며, 구성 파일이 필요하지 않습니다 (선택적 보관소 제외).

도구 상세 정보

web_search

web_search(query, max_results=5, summarize=False, auto_fetch_top=False)

최대 신뢰성을 위해 3단계 캐스케이드를 사용하여 웹을 검색합니다:

1. Brave Search API — 빠르고 고품질 (BRAVE_API_KEY 필요)

2. DuckDuckGo 라이브러리 — API 키 불필요, 속도 제한 시 재시도

3. DuckDuckGo HTML 스크레이퍼 — 최후의 수단

옵션:

• summarize: Ollama를 사용하여 결과 요약 (Ollama 실행 필요)

• auto_fetch_top: 상위 결과의 전체 콘텐츠도 가져와서 반환

fetch_url

fetch_url(url, summarize=False, max_chars=15000)

URL을 가져와 깔끔한 마크다운으로 변환합니다:

• SSRF 보호: 로컬호스트, 사설 IP, 비 HTTP 스키마 차단

• 스마트 재시도: 429/5xx 오류 시 지수 백오프, 홉별 리다이렉트 검증

• 24시간 캐시: SHA-256 키 기반, 구성 가능한 TTL

• 콘텐츠 지원: HTML → 마크다운, JSON → 코드 블록, 바이너리 → 거부

• 스마트 잘림: 텍스트 중간이 아닌 제목/단락 경계에서 끊음

• CAPTCHA 감지: Cloudflare, hCaptcha, reCAPTCHA, Akamai 차단벽 플래그 지정

• 토큰 효율성: 기본 15K 문자 (약 4K 토큰), max_chars를 통해 조정 가능

research

research(query, depth="standard", context="")

복합 조사 파이프라인:

1. 쿼리 재작성 — Ollama가 질문을 검색 키워드로 최적화

2. 웹 검색 — 관련 페이지 찾기 (결과가 없을 경우 재시도 확장)

3. 병렬 가져오기 — 상위 N개 페이지를 동시에 가져오기

4. 요약 — Ollama가 각 페이지 요약

5. 합성 — Ollama가 최종 인용 답변 생성

깊이 수준:

모든 단계는 Ollama 없이도 정상적으로 작동하며, 검색 결과와 페이지 콘텐츠를 얻을 수 있습니다.

youtube_essence

youtube_essence(url, mode="standard")

YouTube 동영상에서 구조화된 콘텐츠 추출:

• 스크립트: 자동 자막 또는 Whisper 전사 (로컬, 비공개)

• 요약: Ollama를 통한 AI 요약

• 핵심 포인트: 불렛 포인트 요약

• 챕터: 타임스탬프가 포함된 세그먼트

• 인용구: 주목할 만한 인용구 (deep 모드)

모드: quick (요약), standard (+ 챕터), deep (+ 인용구)

yt-dlp가 필요합니다. 선택 사항: 오디오 전용 동영상을 위한 faster-whisper, 미디어 추출을 위한 ffmpeg.

deep_ingest

deep_ingest(path, include_types="", max_files=200, summarize=False)

디렉토리 내 파일 또는 단일 파일에서 텍스트 추출:

• 텍스트 파일: .txt, .md, .json, .csv, 소스 코드 등

• PDF: PyPDF2를 통해 (선택적 종속성)

• Office: .docx, .xlsx, .pptx (선택적 종속성)

• 오디오/비디오: Whisper 전사 (선택 사항)

• 이미지: Ollama 비전 모델을 통한 OCR (선택 사항)

유형 필터: text, pdf, audio, video, image, office

academic_lookup

academic_lookup(identifier, fetch_fulltext=True)

여러 식별자 유형에서 학술 논문 확인:

• DOI: 10.xxxx/... → Crossref 메타데이터 + 게시자 리다이렉트

• ArXiv: 2301.12345 → 초록 + PDF

• PubMed: PMID → E-utilities 메타데이터 → DOI 체인

• URL: 게시자 페이지 감지

자격 증명 보관소를 통한 전문 접근:

• EZproxy 재작성 (접두사 및 접미사 모드)

• Bearer 토큰, API 키, 기본 인증, 쿠키 저장소

• 자동 게시자 감지 (IEEE, Springer, Elsevier, ACM, Wiley, Nature, JSTOR 등)

twitter_extract

twitter_extract(url, include_thread=False)

전략 캐스케이드를 사용하여 X.com/Twitter에서 트윗 및 스레드 추출:

1. yt-dlp (기본) — 인증된 접근을 위해 쿠키 저장소와 함께 작동

2. Twitter API v2 — 보관소에 Bearer 토큰이 구성된 경우

3. HTML 가져오기 — 쿠키 기반 최후의 수단

반환값: 텍스트, 작성자, 타임스탬프, 지표(좋아요, 리트윗, 답글), 미디어 URL.

vault_status

vault_status()

로드된 자격 증명 프로필, 일치 패턴 및 인증 유형을 표시합니다. 비밀 정보는 절대 노출하지 않습니다. 또한 선택적 종속성의 가용성을 확인합니다.

자격 증명 보관소

~/.mcp-research/vault.yaml을 생성하여 보호된 소스에 대한 인증을 구성하세요:

version: 1
profiles:
 # University EZproxy for IEEE
 ieee-university:
 match: "*.ieee.org/**"
 ezproxy:
 base_url: "https://ezproxy.myuniversity.edu/login?url="
 mode: prefix

 # Springer via API key
 springer:
 match: "*.springer.com/**"
 auth:
 type: api_key
 header: "X-ApiKey"
 value: "${SPRINGER_API_KEY}"

 # X.com via browser cookies
 twitter:
 match: "*.x.com/**"
 auth:
 type: cookie_jar
 path: "${HOME}/.mcp-research/cookies/twitter.txt"

• ${VAR}은 환경 변수에서 확인됩니다. 비밀 정보는 일반 텍스트로 저장되지 않습니다.

• 첫 번째 일치 프로필이 우선합니다 (순서 중요).

• 인증 유형: bearer, basic, api_key, cookie_jar, headers

• EZproxy 모드: prefix (기본 URL 앞에 추가) 또는 suffix (도메인 재작성)

• 핫 리로드: 보관소 파일 변경 사항이 자동으로 적용됩니다.

토큰 효율성

모든 도구는 AI 컨텍스트 창 토큰 낭비를 방지하기 위해 기본적으로 압축된 출력을 생성합니다:

안전성 및 견고성

• SSRF 보호: 모든 홉에서 로컬호스트, 사설 IP, 링크 로컬, 비 HTTP 스키마 차단

• CAPTCHA 감지: Cloudflare, hCaptcha, reCAPTCHA, Akamai, DDoS-Guard 차단벽 식별

• 입력 검증: 크기 제한, URL 검증, 안전한 리다이렉트 추적

• No eval/exec: 동적 코드 실행 없음

• 보관소 보안: 환경 변수에서 비밀 정보 확인, repr()로 모든 인증 값 마스킹

• 캐시 격리: 소유자 전용 디렉토리 권한 (0o700)

• 우아한 저하: 누락된 선택적 종속성이 충돌을 일으키지 않으며, 명확한 메시지와 함께 기능이 저하됨

CLI

mcp-research serve # Run MCP stdio server (default)
mcp-research search "query" # Search the web
mcp-research fetch https://example.com # Fetch URL to markdown
mcp-research youtube https://youtu.be/... # Extract YouTube video
mcp-research ingest ./docs/ # Extract text from files
mcp-research academic "10.1109/..." # Resolve academic paper
mcp-research tweet https://x.com/.../123 # Extract tweet
mcp-research vault # Show vault profiles
mcp-research doctor # Check dependencies

개발

git clone https://github.com/MABAAM/Maibaamcrawler.git
cd Maibaamcrawler
pip install -e ".[all]"
pytest tests/ -v
python -m mcp_research

변경 로그

v0.3.0

• 자격 증명 보관소: 환경 변수 보간, Glob URL 일치, EZproxy 재작성, 핫 리로드를 지원하는 ~/.mcp-research/vault.yaml 구성

• 세션 풀링: 보관소 인증 주입, 쿠키 저장소 지원, 유휴 퇴거를 포함한 도메인별 세션

• CAPTCHA 감지: Cloudflare, hCaptcha, reCAPTCHA, Akamai, DDoS-Guard, 일반 봇 차단벽 식별

• 학술 조회: DOI/ArXiv/PubMed 확인, Crossref 메타데이터, 보관소를 통한 기관 전문 접근

• Twitter/X 추출: yt-dlp, API v2 및 스레드 지원을 포함한 쿠키 기반 접근

• 토큰 효율성: AI 컨텍스트 보존을 위한 기본 출력 제한 (가져오기 시 ~4K 토큰, 조사 소스당 ~500 토큰)

• Doctor 명령: mcp-research doctor가 모든 종속성 및 구성 확인

• Windows 인코딩 수정: UTF-8 stdout/stderr 래퍼가 cp1252 충돌 방지

v0.2.0

• YouTube 에센스: 스크립트 추출, AI 요약, 핵심 포인트, 챕터, 인용구

• Deep ingest: PDF, DOCX, XLSX, PPTX, 오디오, 비디오, 이미지 텍스트 추출

• Ollama 통합: 쿼리 재작성, 요약, 합성, 비전 OCR

• 검색 로깅: 모든 작업에 대한 NDJSON 이벤트 로그

• Brave Search: API 키 지원을 포함한 기본 검색 계층

v0.1.0

• 초기 릴리스: 3개 도구 (web_search, fetch_url, research), SSRF 보호, 캐싱

라이선스

MIT

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• academic_lookupA
• deep_ingestA
• fetch_urlA
• researchA
• twitter_extractA
• vault_statusA
• web_searchA
• youtube_essenceA