Skip to main content
Glama
Sign In
everything-semantic-mcp

everything-semantic-mcp

by yazzang-homelab
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

findex

파일 이름을 몰라도 찾는 검색 — 사람은 검색 창으로, AI 에이전트는 MCP로. Windows · macOS · Linux 실행 파일 하나. 설치·Python 불필요.

한국어 · English

⬇ 최신 버전 다운로드

이런 걸 찾습니다

이렇게 검색하면

이름 검색만으로는

findex

신입 교육 자료

0건 (예: 실제 폴더명이 "신입사원 온보딩 가이드"일 때)

상위로 찾음

분기 매출 보고서 위치

0건 ("위치"라는 단어가 이름에 없음)

"2026 Q3 매출 보고서" 폴더 상위

budget ext:xlsx dm:last30days

정상

그대로 정확 검색

  • 이름 검색: Everything 문법(ext:, path:, dm:, size:, folder:, !, |, *).

  • 단어 하나가 안 맞아도: 모든 단어가 들어간 항목이 없으면, 가장 많은 단어가 맞는 순으로 보여줍니다(BM25 보조).

  • 뜻으로 찾기: 폴더·문서 이름을 다국어 임베딩으로 색인. 한국어·영어 섞어도 됩니다. 전부 내 PC 안에서.

Related MCP server: everything-search-mcp

시작하기 (1분)

  1. Releases 에서 내 OS 파일을 받습니다.

    OS

    파일

    Windows 10/11

    findex-windows-x64.exe

    macOS Apple Silicon (M1~)

    findex-macos-arm64 (Intel Mac: 소스로 실행, 아래 참고)

    Linux x64

    findex-linux-x64

  2. 실행 — 더블클릭하면 브라우저에 검색 창이 열립니다.

    • Windows SmartScreen이 막으면 "추가 정보 → 실행" (서명 인증서 없는 오픈소스 빌드).

    • macOS: 터미널에서 xattr -d com.apple.quarantine ~/Downloads/findex-macos-*; chmod +x ~/Downloads/findex-macos-* 후 실행.

    • Linux: chmod +x findex-linux-x64 && ./findex-linux-x64

  3. 처음 한 번 검색 창 위쪽의 "의미 색인 만들기" 를 누릅니다(모델 약 120MB 자동 다운로드, 수 분).

어떤 색인을 쓰나요?

  • Windows + Everything 실행 중 → Everything의 색인을 그대로 사용(수백만 개도 즉시).

  • 그 외(macOS·Linux·Everything 없는 Windows) → findex가 자체 색인을 만듭니다. 첫 실행 때 홈 폴더(Windows는 고정 드라이브 전체)를 스캔합니다.

    • 범위 바꾸기: findex roots add /Volumes/NAS, findex roots remove ~/Downloads, 다시 스캔: findex scan

AI 에이전트에 연결 (MCP)

실행 파일 경로를 command로, 인자 mcp를 넣으면 됩니다.

Claude Code

claude mcp add findex -- /경로/findex mcp

Claude Desktop (claude_desktop_config.json)

{ "mcpServers": { "findex": { "command": "C:\\Tools\\findex-windows-x64.exe", "args": ["mcp"] } } }

Codex CLI / Cursor / gjc 등: 같은 command + args: ["mcp"].

에이전트가 쓰는 도구:

도구

용도

everything_find

자연어 요청 한 번에 — 이름 매칭 + 의미 검색 융합

everything_search

정확한 이름 검색·필터·정렬 (0건이면 가장 많이 맞는 순으로 자동 완화)

everything_count / everything_recent / everything_largest

건수 비교 / 최근 수정 / 큰 파일

everything_semantic_search / everything_semantic_reindex

의미만으로 검색 / 의미 색인 생성

everything_status / everything_rescan

상태 / 자체 색인 재스캔

everything_health / everything_maintain

Everything 설정 자가 진단 / DB 저장·재스캔 (Windows + Everything)

명령줄

findex                 검색 창 열기 (기본)
findex mcp             MCP 서버 (stdio)
findex scan            자체 이름 색인 새로고침
findex reindex         의미 색인 만들기
findex roots [add|remove DIR]   자체 색인 범위
findex status | health

측정값

Windows 11 · i7-1255U · Everything 1.4.1.1032 x64 · 색인 6,126,653 항목(로컬 + 네트워크 폴더):

항목

값

의미 색인

1,177,343개 이름, 생성 264초

의미 검색 1회 (중앙값)

45~58 ms

find (이름+의미 융합, 예열 후 중앙값)

약 440 ms

2단계 재정렬 recall@20

0.98 (전수 256차원 대비)

시작 직후 첫 의미 검색

모델 로딩 약 20초 — 검색 창은 이름 결과를 먼저 보여주고 의미 결과는 준비되면 합류

실제 사내 경로 78만 개로 평가한 검색 방식 비교(한 단어가 이름에 없는 질의 200개): 엄격한 이름 검색은 89%가 0건, 단어 완화 + 순위(findex)는 53%가 상위 10위 안에 정답. 주제 질의 20개는 이름+의미 융합이 상위 10위 적중 0.90~0.95.

개인정보

  • 파일 내용은 읽지 않고 이름·경로·크기·날짜만 색인합니다.

  • 모든 처리는 내 PC 안에서. 외부 전송은 최초 모델 다운로드(Hugging Face)뿐입니다.

  • 색인 위치: Windows %LOCALAPPDATA%\findex, macOS ~/Library/Application Support/findex, Linux ~/.local/share/findex. 경로가 평문으로 저장되니 공유 PC라면 권한을 확인하세요.

  • 검색 창은 127.0.0.1에만 열립니다(외부 접속 불가).

소스로 실행 / 개발

git clone https://github.com/yazzang-homelab/everything-semantic-mcp
cd everything-semantic-mcp
pip install -e ".[dev]"
findex            # 또는 python -m everything_semantic_mcp
pytest

실행 파일 빌드: cd packaging && pyinstaller findex.spec (각 OS에서). 태그(v*)를 올리면 GitHub Actions가 4개 OS용으로 빌드·테스트·릴리스합니다.

관련 프로젝트

elis132/everything-mcp(es.exe 기반, 느린 쿼리 보호), mamertofabian/mcp-everything-search(SDK DLL, macOS/Linux 지원). findex는 독립적으로 작성했고 의미 검색 + 단어 완화 검색 + 사람용 검색 창 + 단일 실행 파일에 집중합니다.

라이선스

MIT. voidtools Everything의 비공식 연동이며, Everything은 voidtools의 상표입니다.

Available Tools

9 tools
everything_countA

Count matches for up to 20 queries in one call (no rows returned), e.g. compare 'ext:pdf' vs 'ext:docx' under a folder, or check whether a file exists anywhere.

Inputs: queries (required), match_path.

everything_healthA

Index health and configuration self-check: version, build (x86/x64), database state, indexed volumes and folders, database age, and settings that cause slow indexing, RAM bloat or freezes (a drive indexed twice, change monitoring on network folders, foreground rescans, rescans at every startup, an index never saved, the 32-bit build). Each issue has a fix.

Inputs: no named parameters.

everything_largestA

Largest files (optionally under a folder or share), for disk-usage triage. min_size: '100mb', '1gb'.

Inputs: limit, min_size, path_filter.

everything_maintainA

Index maintenance. save_db: persist the in-memory index (fast restart). rescan_folders: refresh folder indexes (network shares) now. rebuild: full re-index (slow; only if results look stale).

Inputs: action (required).

everything_recentA

Most recently modified files, newest first.

path_filter: restrict to a folder or share. extensions: ';'-separated, e.g. 'xlsx;csv'. within: today | yesterday | last7days | last30days | thisweek | thismonth | 2026-10.

Inputs: limit, within, extensions, path_filter.

everything_searchB

Search file and folder names across every drive and network folder Everything indexes.

query: Everything syntax, e.g. 'ext:xlsx budget dm:last30days', 'path:"D:\Projects" *.pptx', 'folder: invoices', '"exact name.txt"'. An empty query matches everything (use with filters). limit: 1-500 rows; total in the response tells you whether to narrow the query. sort: name (always instant) | date_modified_desc for "latest" | size_desc for "largest". details: include size (bytes) and modification date; false returns bare paths (folders end with ''). match_path: match terms against the full path instead of just the name.

Inputs: query (required), sort, limit, regex, +5 more.

everything_semantic_reindexA

(Re)build the local semantic index from the live Everything database. Runs in the background unless wait=true (~3-7 min per million names on a laptop CPU); poll everything_semantic_status.

Inputs: wait.

everything_semantic_searchA

Meaning-based search over folder names and document file names (multilingual, fully local). Use when the user describes WHAT they want rather than a literal name: 'last quarter's sales deck', '세금 계산서 모음', 'onboarding material'. Scores: >0.6 strong, 0.4-0.6 related. path_prefix restricts to a drive or share. Folders end with ''; list their contents with everything_search('parent:""').

Inputs: query (required), kind, limit, path_prefix.

everything_semantic_statusC

Semantic index metadata (count, built_at, model), its location, and any running or failed build.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool has a recognizable purpose: literal search vs semantic search is clearly split, and count/recent/largest/health/maintain/reindex/status all target distinct operations. The only mild overlap is that everything_recent and everything_largest are effectively presets of everything_search with a sort argument, but the descriptions frame them distinctly enough that misselection is unlikely.

    Naming Consistency5/5

    Every tool uses the same everything_ prefix followed by a clear action descriptor (search, count, recent, largest, health, maintain, and the semantic_ family). The verb_noun-ish pattern is consistent across the whole set, including the namespaced semantic group.

    Tool Count5/5

    Nine tools is well within the ideal 3-15 range for a focused file-search server. Each earns its place: two search modes, three aggregation helpers, two index-health tools, and two semantic-index lifecycle tools.

    Completeness4/5

    The surface covers literal and semantic discovery, aggregation (count/recent/largest), and index health/maintenance/reindex lifecycle well, so core workflows have no dead ends. Minor gaps remain, such as opening/revealing the file found or exporting results, which agents would have to work around.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • everything-search-mcp

      miloira
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to search local files on Windows using the Everything search engine, supporting basic and complex file searches with filters like date, size, media type, and document type.
      15 PyPI
      4
      MIT

    • Everything MCP Server

      CastleYu
      A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to search local files and folders via the Everything search engine, with support for advanced queries, file metadata, text previews, and service status.
      6
      157 npm
      MIT