FileScope MCP server

FileScopeMCP is a powerful tool for analyzing and visualizing codebase structure and dependencies. It ranks files by importance, tracks dependencies, and provides summaries to help understand your code structure—all accessible through Cursor's Model Context Protocol.

Installation

Setting Up the MCP Server

1. Clone the repository

2. Build the project:

   Windows:

   build.bat
   

   Linux: (For Windows Cursor with project in Linux WSL)

   build.sh
   

3. Configure Cursor by copying the generated mcp.json to your project's .cursor directory:

   Windows configuration:

   {
     "mcpServers": {
       "FileScopeMCP": {
         "command": "node",
         "args": ["<path to mcp-server.js>","--base-dir=C:/Users/username/my/project/base"],
         "transport": "stdio",
         "disabled": false,
         "alwaysAllow": []
       }
     }
   }
   

   Linux configuration:

   {
     "mcpServers": {
       "FileScopeMCP": {
         "command": "wsl",
         "args": ["-d", "Ubuntu-24.04", "/home/username/FileScopeMCP/run.sh"],
         "transport": "stdio",
         "disabled": false,
         "alwaysAllow": []
       }
     }
   }
   

4. Update the --base-dir argument to point to your project's base path.

Using FileScopeMCP

The MCP server provides several tools to analyze and understand your codebase.

Managing File Trees

create_file_tree(filename: "my-project.json", baseDirectory: "/path/to/project")
list_saved_trees()
select_file_tree(filename: "my-project.json")
delete_file_tree(filename: "old-project.json")

Analyzing Files

list_files()
get_file_importance(filepath: "/path/to/project/src/main.ts")
find_important_files(limit: 5, minImportance: 5)
read_file_content(filepath: "/path/to/project/src/main.ts")
recalculate_importance()

Working with File Summaries

set_file_summary(filepath: "/path/to/project/src/main.ts", summary: "Main entry point that initializes the application.")
get_file_summary(filepath: "/path/to/project/src/main.ts")

Generating Diagrams

generate_diagram(style: "directory", maxDepth: 3, outputPath: "diagrams/project-structure", outputFormat: "mmd")

You can customize diagrams with various options:

• styles: "default", "dependency", "directory", or "hybrid"
• outputFormat: "mmd" or "html"
• layout: Customize direction (TB, BT, LR, RL), node spacing, and rank spacing
• filters: Set maxDepth and minImportance to focus on relevant portions

Example for Generating HTML Dependency Diagram

generate_diagram(
  style: "hybrid", 
  maxDepth: 2, 
  minImportance: 5, 
  showDependencies: true, 
  outputPath: "diagrams/important-files", 
  outputFormat: "html"
)

Configuring File Watching

toggle_file_watching()
get_file_watching_status()
update_file_watching_config(config: { 
  debounceMs: 500, 
  autoRebuildTree: true,
  watchForNewFiles: true,
  watchForDeleted: true,
  watchForChanged: true
})

Quick Start Workflow

1. Enable the MCP in Cursor
2. Create a file tree for your project
3. Find the most important files in your codebase
4. Use an LLM to generate summaries for important files
5. Store these summaries using set_file_summary
6. Generate diagrams to visualize relationships
7. Enable file watching to keep information updated

The server automatically detects imports and dependencies across multiple languages including Python, JavaScript/TypeScript, C/C++, Rust, Lua, Zig, C#, and Java.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "FileScopeMCP" '{"command":"node","args":["<build script sets this>/mcp-server.js","--base-dir=C:/Users/admica/my/project/base"],"transport":"stdio","disabled":false,"alwaysAllow":[]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "FileScopeMCP": {
            "command": "node",
            "args": [
                "<build script sets this>/mcp-server.js",
                "--base-dir=C:/Users/admica/my/project/base"
            ],
            "transport": "stdio",
            "disabled": false,
            "alwaysAllow": []
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "FileScopeMCP": {
            "command": "node",
            "args": [
                "<build script sets this>/mcp-server.js",
                "--base-dir=C:/Users/admica/my/project/base"
            ],
            "transport": "stdio",
            "disabled": false,
            "alwaysAllow": []
        }
    }
}

3. Restart Claude Desktop for the changes to take effect