What can you do with this server?

The Vexor MCP server provides semantic file search and indexing as native tools for any MCP-compatible AI agent or client (Claude Code, Cursor, Windsurf, etc.). * Semantic File Search (vexor_search): Find files by describing what they do or contain in natural language, without knowing exact names or paths. Returns ranked results with relevance scores, file paths, line ranges, and text previews. * Configurable result count (1–50, default 5), recursive search, file extension filters, gitignore-style exclusion patterns, hidden file inclusion, and .gitignore respect * Index granularity modes: auto, name, head, brief, full, code (AST-chunked), or outline (Markdown headings) * Auto-indexes on first search when auto_index is enabled * Index Building/Refreshing (vexor_index): Explicitly build or refresh the semantic index for a directory. Useful for CI warmup or when auto-indexing is disabled. Returns index status (stored, up_to_date, or empty) and the number of files indexed. Supports the same granularity modes and filtering options as search.

Which integrations are available for this server?

Provides embedding models (Gemini) for semantic search indexing. Provides embedding models for semantic search indexing via OpenAI's API.

vexor

by scarletkc

Overview Schema Related Servers Score Discussions

Python

Local

Vexor

Python PyPI Codecov CodeRabbit Pull Request Reviews License Ask DeepWiki

Vexor is a semantic search engine that builds reusable indexes over files and code. It supports configurable embedding and reranking providers, and exposes the same core through a Python API, a CLI tool, and an MCP server.

Featured In

Vexor has been recognized and featured by the community:

Ruan Yifeng's Weekly (Issue #379) - A leading tech newsletter in the Chinese developer community.
Awesome Claude Skills - Curated list of best-in-class skills for AI agents.
Awesome MCP Servers - Curated list of Model Context Protocol servers.
Awesome CLI Apps - Curated list of command-line apps.

Related MCP server: semantic-search-mcp

Why Vexor?

When you remember what a file does but forget its name or location, Vexor finds it instantly—no grep patterns or directory traversal needed.

Designed for both humans and AI coding assistants, enabling semantic file discovery in autonomous agent workflows.

Install

Download standalone binary from releases (no Python required), or:

pip install vexor  # also works with pipx, uv

Quick Start

0. Guided Setup (Recommended)

vexor init

The wizard also runs automatically before the first interactive operational command when no config exists. Configuration-management (vexor config), MCP, help, and version commands run directly.

1. Search

vexor "api client config"  # defaults to search current directory
# or explicit path:
vexor search "api client config" --path ~/projects/demo --top 5
# in-memory search only:
vexor search "api client config" --no-cache

Vexor auto-indexes on first search. Example output:

Vexor semantic file search results
──────────────────────────────────
#   Similarity   File path                       Lines   Preview
1   0.923        ./src/config_loader.py          -       config loader entrypoint
2   0.871        ./src/utils/config_parse.py     -       parse config helpers
3   0.809        ./tests/test_config_loader.py   -       tests for config loader

2. Explicit Index (Optional)

vexor index  # indexes current directory
# or explicit path:
vexor index --path ~/projects/demo --mode code

Useful for CI warmup or when auto_index is disabled.

Python API

Vexor can also be imported and used directly from Python:

from vexor import index, search

index(path=".", mode="head")
response = search("config loader", path=".", mode="name")

for hit in response.results:
    print(hit.path, hit.score)

Configuration follows the same global and project-level resolution as the CLI. For runtime overrides, cache controls, and per-call options, see docs/api/python.md.

AI Agent Skill

This repo includes a skill for AI agents to use Vexor effectively:

vexor install --skills claude  # Claude Code
vexor install --skills codex   # Codex

Skill source: plugins/vexor/skills/vexor-cli

MCP Server

vexor MCP server

NOTE

The Agent Skill and the MCP server provide the same core capability — pickone per agent. The skill teaches shell-capable agents (Claude Code, Codex) to drive the full CLI and assumes vexor is installed on PATH; the MCP server exposes search as native tools, works in any MCP client (Cursor, Windsurf, Zed, ...), and can bootstrap without prior setup via uvx and environment variables.

Vexor ships a built-in MCP stdio server, so any MCP-capable agent can use semantic file search as a native tool:

claude mcp add vexor -- vexor mcp   # Claude Code
codex mcp add vexor -- vexor mcp    # Codex

Or configure manually in any MCP client, optionally supplying the API key and any config overrides via env (no vexor init needed):

{
  "mcpServers": {
    "vexor": {
      "command": "vexor",
      "args": ["mcp"],
      "env": {
        "VEXOR_API_KEY": "sk-...",
        "VEXOR_CONFIG_JSON": "{\"provider\": \"gemini\", \"rerank\": \"bm25\"}"
      }
    }
  }
}

The server exposes two tools: vexor_search (semantic file search, returning the matching source text so an agent rarely needs a follow-up file read) and vexor_index (explicit index warm-up). No extra dependencies are required. Vexor is listed on the official MCP registry as io.github.scarletkc/vexor. See docs/mcp.md for tool schemas, environment variables, and client setup details.

Configuration

vexor init                             # guided setup (recommended)
vexor config --set-api-key "YOUR_KEY"  # or env: VEXOR_API_KEY / OPENAI_API_KEY / ...
vexor config --set-provider openai     # default; also gemini/voyageai/custom/local
vexor config --rerank hybrid           # optional: fuse exact keyword + semantic ranking
vexor config --show                    # view effective settings and origins

Global config lives in ~/.vexor/config.json; the nearest <project>/.vexor/config.json can override a restricted set of behavior fields for that project. Non-secret fields can also be injected via VEXOR_CONFIG_JSON (useful for MCP clients and CI), and fully offline use is supported through local embedding models.

See docs/configuration.md for the complete reference: project config fields and precedence, all config commands, API keys and environment variables, rerank strategies (hybrid / BM25 / FlashRank / remote), remote vs local providers, embedding dimensions, and offline local model setup.

CLI Reference

Everyday usage fits in vexor "query", vexor search, and vexor index (see Quick Start). The full command table, common flags, index modes (--mode auto/name/head/brief/full/code/outline), .vexorignore files, project-local indexes (vexor index --local), cache behavior, and porcelain output format are documented in docs/cli.md.

Documentation

Configuration — providers, API keys, rerank, embedding dimensions, local models
CLI reference — commands, flags, index modes, cache behavior
MCP server — client setup, environment variables, tool schemas
Python API — programmatic usage
Collections API — database-backed text records and filtered search

Contributing

Contributions, issues, and PRs welcome! Commit messages and PR titles follow Conventional Commits (e.g. feat(mcp): add stdio server). Star if you find it helpful.

Star History

License

MIT

Available Tools

2 tools

vexor_indexA

Build or refresh the semantic index for a directory. Use it to warm the cache or when auto_index is disabled.

ParametersJSON Schema

Name	Required	Description	Default
`mode`	No	Index granularity: auto routes per file type; name embeds filenames only; head/full/brief cover content depth; code chunks by AST; outline chunks Markdown by headings.	auto
`path`	No	Directory to operate on. Absolute, or relative to the server's default path (/app).
`local`	No	Create <path>/.vexor and store this project's index there
`recursive`	No	Recurse into subdirectories (default). Set false to scan only the top level of the directory.
`extensions`	No	Only include these file extensions, e.g. ['.py', '.md'].
`include_hidden`	No	Include dot-prefixed files and directories such as .github or .env (excluded by default).
`exclude_patterns`	No	Gitignore-style patterns to exclude.
`respect_gitignore`	No	Honor .gitignore rules (default). Set false to also scan ignored files such as build output.

Output Schema

ParametersJSON Schema

Name	Required	Description
`mode`	Yes
`path`	Yes
`status`	Yes
`files_indexed`	Yes

TDQS

A3.5/5.0

Behavior2/5

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

No annotations are provided, so the description must fully disclose behavioral traits. It only says 'Build or refresh,' lacking details on destructiveness (e.g., whether refresh overwrites), auth requirements, rate limits, or side effects. This leaves significant gaps for an AI agent.

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 two sentences, very concise, and front-loaded with the core purpose. Every word earns its place with no fluff.

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

Completeness3/5

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

The description is short but covers the basic purpose. With 8 parameters and an output schema, it could mention how the output is structured or reference the sibling tool for fuller context. It is adequate but not thorough.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all parameters. The tool description adds no additional parameter information beyond what is in the schema, meeting the baseline but not exceeding it.

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

Purpose4/5

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

The description states 'Build or refresh the semantic index for a directory,' which is a specific verb+resource. It adds context with 'warm the cache or when auto_index is disabled,' but does not explicitly distinguish from its sibling tool 'vexor_search,' though the purpose seems distinct enough.

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?

The description provides clear usage scenarios (warm cache, auto_index disabled), giving context for when to use the tool. However, it does not mention when not to use it or alternatives like the sibling tool, which keeps it from a 5.

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

vexor_searchA

Find files or code from a natural-language description. Returns ranked matches with paths, relevance scores, line ranges, and the matching source text, so most results need no follow-up file read.

ParametersJSON Schema

Name	Required	Description	Default
`top`	No	Number of results to return.
`mode`	No	Index granularity: auto routes per file type; name embeds filenames only; head/full/brief cover content depth; code chunks by AST; outline chunks Markdown by headings.	auto
`path`	No	Directory to operate on. Absolute, or relative to the server's default path (/app).
`query`	Yes	Natural-language description of the file or code you are looking for, e.g. 'where API retries are configured'.
`no_cache`	No	Build a temporary in-memory index and disable all disk caches for this search. Slower and may regenerate embeddings.
`recursive`	No	Recurse into subdirectories (default). Set false to scan only the top level of the directory.
`extensions`	No	Only include these file extensions, e.g. ['.py', '.md'].
`content_budget`	No	Total characters of source text one response may return, spent on the highest-ranked matches first.
`include_hidden`	No	Include dot-prefixed files and directories such as .github or .env (excluded by default).
`include_content`	No	Return each match's source text alongside its path. Text is read from the file at search time. A result carries content_unavailable instead when the mode records no line range, the file changed since indexing, or the budget ran out.
`exclude_patterns`	No	Gitignore-style patterns to exclude.
`respect_gitignore`	No	Honor .gitignore rules (default). Set false to also scan ignored files such as build output.

Output Schema

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`query`	Yes
`stale`	Yes
`backend`	Yes
`results`	Yes
`reranker`	Yes
`index_empty`	Yes
`content_budget`	No

TDQS

A3.6/5.0

Behavior3/5

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

With no annotations, the description carries the full transparency burden. It discloses that results include source text, reducing the need for a follow-up read—a helpful behavioral detail. However, it omits many behavioral traits: possible side effects of the `no_cache` parameter (temporary in-memory index), the conditional availability of content based on `content_budget`, and the fact that `include_content` can return 'content_unavailable'. The description gives partial insight but is not comprehensive enough to fully replace annotations.

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 two sentences and immediately states the core action. Every word serves a purpose: the first sentence defines the verb+noun, the second completes the picture by listing return fields and a practical implication (reducing follow-ups). No fluff, adequately front-loaded.

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

Completeness2/5

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

Despite an output schema existing (reducing the need to document returns), the description fails to provide context for the 12-parameter complexity. It does not mention the `mode`, `path`, `extensions`, `exclude_patterns`, or `no_cache` parameters that significantly alter behavior. No guidance on when to use this vs. `vexor_index`. For a tool with this many knobs and a sibling, the description is too terse to be considered complete.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The tool description adds no additional parameter context beyond what the schema already provides—it does not mention any parameters or their roles. The description earns credit only for its overall purpose, not for parameter semantics, thus meeting but not exceeding the baseline.

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 starts with 'Find files or code from a natural-language description,' a specific verb+resource pair that clearly states the tool's goal. It distinguishes from the sibling 'vexor_index' (which likely manages an index) by focusing on retrieval, not indexing. The return value summary further solidifies purpose.

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

Usage Guidelines3/5

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

The description implies the tool should be used for natural-language file searches, but provides no explicit when-to-use or when-not-to-use guidance. It does not mention the sibling 'vexor_index' as an alternative or prerequisite, and offers no exclusions. The context is acceptable but minimal, leaving the agent to infer usage without direction.

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.27.1Aug 18, 2026

Changedvexor_search8 fields changed

addedInput schema / properties / content_budget

Added value: +{
+  "default": 8000,
+  "description": "Total characters of source text one response may return, spent on the highest-ranked matches first.",
+  "maximum": 40000,
+  "minimum": 500,
+  "type": "integer"
+}

addedInput schema / properties / include_content

Added value: +{
+  "default": true,
+  "description": "Return each match's source text alongside its path. Text is read from the file at search time. A result carries content_unavailable instead when the mode records no line range, the file changed since indexing, or the budget ran out.",
+  "type": "boolean"
+}

addedOutput schema / properties / content_budget

Added value: +{
+  "properties": {
+    "limit": {
+      "type": "integer"
+    },
+    "used": {
+      "type": "integer"
+    }
+  },
+  "required": [
+    "limit",
+    "used"
+  ],
+  "type": [
+    "object",
+    "null"
+  ]
+}

addedOutput schema / properties / results / items / properties / content
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```
addedOutput schema / properties / results / items / properties / content_end_line
```
Added value: +{
+  "type": [
+    "integer",
+    "null"
+  ]
+}
```
addedOutput schema / properties / results / items / properties / content_start_line
```
Added value: +{
+  "type": [
+    "integer",
+    "null"
+  ]
+}
```
addedOutput schema / properties / results / items / properties / content_truncated
```
Added value: +{
+  "type": "boolean"
+}
```
addedOutput schema / properties / results / items / properties / content_unavailable
```
Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}
```

2 tool updatesv0.25.0Jul 14, 2026

Changedvexor_index1 field changed

addedInput schema / properties / local

Added value: +{
+  "default": false,
+  "description": "Create <path>/.vexor and store this project's index there",
+  "type": "boolean"
+}

Changedvexor_search2 fields changed

addedInput schema / properties / no_cache

Added value: +{
+  "default": false,
+  "description": "Build a temporary in-memory index and disable all disk caches for this search. Slower and may regenerate embeddings.",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "query",
-  "path",
-  "results"
-]New value: +[
+  "query",
+  "path",
+  "backend",
+  "reranker",
+  "stale",
+  "index_empty",
+  "results"
+]

2 tool updatesv0.1.0Jul 13, 2026
- First observedvexor_index
- First observedvexor_search

Install Server

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

TDQS

A3.8/5.0

Disambiguation5/5

The two tools have completely distinct purposes: one for searching and one for indexing. There is no overlap or confusion between them.

Naming Consistency5/5

Both tools use the consistent 'vexor_' prefix followed by a clear single-word noun ('search', 'index'), forming a predictable verb-less pattern.

Tool Count3/5

With only 2 tools, the server feels thin for a typical MCP server, but the narrow scope of semantic search may justify this. It is at the low end of what is considered acceptable.

Completeness4/5

The two tools cover the core cycle of index and search, and the search tool returns source text, reducing the need for additional file reads. Minor gaps exist (e.g., no status or configuration tools), but for the stated purpose, it is largely complete.

Maintenance

ActivityActive

ResponsivenessResponsive

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Maguyva
ai.maguyva
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code Analysis Coding Agents
23
Nano Studio ProOAuth
com.nanostudiopro
Personal asset search engine: everything you make or upload is searchable by what's inside it.
Image & Video Processing AI & Machine Learning
2
llmref A
org.llmref
Versioned documentation registry and semantic search for AI tools and coding assistants.
Documentation Access Search Developer Tools
42
ContextStream MCP Server
io.github.contextstream
Project memory, semantic code search, and grounded agent context.
Knowledge & Memory Code Analysis RAG Systems
141

Related MCP Servers

Acemcp
Code Analysis Search Developer Tools
qy527145
A
license
A
quality
D
maintenance
Enables semantic code search across codebases with automatic incremental indexing. Searches return relevant code snippets with file paths and line numbers based on natural language queries.
Updated 9 months ago (2025-12-18 04:31 UTC)
1
806
Apache 2.0
semantic-search-mcp
Code Analysis Search Developer Tools
adam-hanna
A
license
A
quality
D
maintenance
Provides semantic code search over codebases using local embeddings with natural language queries. Supports hybrid search, file watching, and respects .gitignore.
Updated 8 months ago (2025-12-30 23:40 UTC)
11
5
MIT
mcp-semantic-search
Search Vector Databases Developer Tools
rohithmahesh3
A
license
A
quality
D
maintenance
Indexes codebases using semantic embeddings for natural language search, enabling developers to find code with queries like 'how does authentication work'.
Updated 8 months ago (2026-01-09 21:11 UTC)
8
1
MIT
Personal File Search MCP
RAG Systems Search Text Summarization
rafiqul713
F
license
Not graded
quality
C
maintenance
Enables semantic search over personal files using natural language, with optional AI summarization, all running locally.
Updated 2 months ago (2026-06-28 13:48 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/scarletkc/vexor'

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

Vexor

Featured In

Why Vexor?

Install

Quick Start

0. Guided Setup (Recommended)

1. Search

2. Explicit Index (Optional)

Python API

AI Agent Skill

MCP Server

Configuration

CLI Reference

Documentation

Contributing

Star History

License

Available Tools

Output Schema

TDQS

Output Schema

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Acemcp

semantic-search-mcp

mcp-semantic-search

Personal File Search MCP

Latest Blog Posts

MCP directory API