Best for
- Developers who need deep codebase context for AI assistants.
- Teams that want to maintain code metadata automatically during development.
- Projects using multiple languages (supports TS/JS, Python, C/C++, Rust, Go, etc.).
F
FileScopeMCP
Community
Your AI already knows how to code. Now it knows your codebase.
GitHub source repository ↗
56FMRS · C
FileScopeMCP is a powerful code analysis tool designed to enhance AI assistants' code understanding. It provides precise context through importance scoring, dependency mapping, and symbol extraction, reducing the need for AI to read source code. Installation is straightforward, with support for multiple languages and clients. Its utility is broad, but it's important to be aware of the heuristic nature of scoring, and the privacy/configuration complexity when using local LLMs.
FileScopeMCP analyzes your codebase, identifying important files based on dependency relationships. It generates diagrams and importance scores per file, helping AI assistants understand the codebase. Automatically parses popular programming languages such as Python, C, C++, Rust, Zig, Lua. It provides tools for querying file summaries, symbol resolution, call graphs, and more.
Tools
status
View broker connection, queue depth, LLM progress, and watcher state.
find_important_files
List top files by importance score with dependency counts.
get_file_summary
Get comprehensive metadata about a file, including summary, concepts, change impact, exports, deps, and staleness.
list_files
Show full file tree or flat top-N by importance.
find_symbol
Resolve a symbol name to file and line range; supports prefix match.
find_callers
Find all symbols that call a named symbol (TS/JS call graph).
find_callees
Find all symbols that a named symbol calls (TS/JS call graph).
search
Search file metadata across symbols, summaries, purpose, and paths.
list_changed_since
List files changed since a timestamp or git SHA.
get_communities
Get Louvain-clustered file groups by import coupling.
detect_cycles
Find circular dependency chains.
get_cycles_for_file
Find cycles involving a specific file.
scan_all
Queue files for LLM summarization via the broker.
set_base_directory
Point at a different project directory.
set_file_summary
Manually set or override a file's summary.
set_file_importance
Manually set a file's importance score (0-10).
exclude_and_remove
Drop files/patterns from tracking (destructive).
Setup
- Clone the repository:
git clone https://github.com/admica/FileScopeMCP. 2. Enter the directory and run./build.shto install dependencies, compile, and register with Claude Code. 3. For other clients, refer todocs/mcp-clients.mdfor manual configuration.
claude_desktop_config.json
{
"type": "stdio",
"command": "node",
"args": [
"/path/to/FileScopeMCP/dist/mcp-server.js"
],
"env": {}
}
Fit and risk
Not for
- Scenarios requiring only a simple file list without dependency analysis.
- Environments without Node.js >=22.
- Fully offline settings without an LLM (though basic features still work).
Required permissions
- File system read and watch permissions (to scan the codebase).
- Write permissions (to create `.filescope/data.db` database).
- Network permissions (optional, to connect to a local LLM endpoint).
Risks and side effects
- Importance scoring is heuristic and may not align with all project preferences.
- Regex-based parsing for some languages may be less accurate than AST.
- LLM summaries depend on external services, potentially raising privacy concerns.
- Database may consume significant space on large codebases.
Troubleshooting
- Ensure Node.js >=22 is installed and build tools (e.g., `build-essential`) are available.
- Check logs; ensure the watcher is running and the `.filescope/data.db` exists.
- If LLM summaries are not generated, verify the local LLM endpoint is configured and reachable.
- Refer to `docs/troubleshooting.md` for common issues and fixes.
Use cases
Enable AI assistants to quickly understand the structure and key files of a large codebase.
Find call relationships and assess impact before refactoring.
Automatically generate and maintain up-to-date file summaries for AI consumption.
Visualize project dependency graphs and community structures.
Supported clients
Claude DesktopFull support
Cursor AIFull support
CodexFull support