TokenScope: Token-Aware Directory Explorer MCP Server

@cdgaete

Basic information

About TokenScope: Token-Aware Directory Explorer MCP Server

A tool to analyze directory structures while being mindful of token limitations for LLMs. Customize ignore files like gitignore patterns, such as .venv or node_modules

#mcp #directory #explorer #claude #ai #assistant#token-aware

TokenScope: Token-Aware Directory Explorer MCP Server config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "TokenScope": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "tokenscope",
        "tokenscope",
        "--base-path",
        "/your/secure/base/path"
      ]
    }
  }
}

TokenScope: Token-Aware Directory Explorer MCP Server tools

Tool list not available yet

This listing does not currently have a tool list to display. This does not mean the server has no tools; check its documentation for supported capabilities.

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is TokenScope: Token-Aware Directory Explorer?

TokenScope is a Model Context Protocol (MCP) server that provides token-aware directory structure analysis and file content extraction for Large Language Models. It helps LLMs understand codebases efficiently by respecting token limits and filtering via .gitignore patterns.

How to use TokenScope: Token-Aware Directory Explorer?

Configure TokenScope with a mandatory base path for security, then invoke its six tools (e.g., scan_directory_structure, extract_file_content, search_files_by_pattern, analyze_token_usage, generate_directory_report, copy_file_to_destination) from any MCP-compatible client. All operations are confined to the allowed directory and automatically respect .gitignore rules.

Key features of TokenScope: Token-Aware Directory Explorer

Recursive directory scanning with token-efficient summaries
Smart file content extraction respecting token limits
Pattern-based file search within the allowed directory
Token usage estimation for entire directories
Comprehensive directory reports with structure and token statistics
Secure file copying between locations inside the base path

Use cases of TokenScope: Token-Aware Directory Explorer

Give an LLM structured context about a codebase before code generation
Extract relevant source files from a large project while staying under token budgets
Estimate the token cost of processing a directory with an LLM
Quickly locate files matching specific patterns in a project
Generate token-aware overviews of directory contents for AI-assisted development

Frequently asked questions

What is the base path and why is it required?

The base path is a mandatory directory that limits all file operations. It ensures security by confining scans, extractions, and copies to that directory only.

How does TokenScope handle token limits?

The server estimates token counts and uses smart extraction to stay within configurable token limits, providing only as much content as the LLM can process.

Does TokenScope respect .gitignore patterns?

Yes, it automatically filters out files and directories matched by .gitignore patterns in the scanned directory, reducing noise and saving tokens.

What are the runtime dependencies of TokenScope?

TokenScope is an MCP server; it requires a runtime environment with the MCP protocol and access to the filesystem it scans. No additional databases or external services are needed.

How secure is file copy in TokenScope?

The `copy_file_to_destination` tool operates exclusively within the allowed base path, preventing any file operations outside that directory. Destination files must also reside inside the base path.

Comments

More Files & Storage MCP servers

box-mcp-server

hmk

A Box model context protocol server to search, read and access files

md-pdf-mcp (Markdown to PDF MCP Server)

seanivore

Markdown To PDF Conversion MCP

Filesystem MCP Server SSE

ysthink

The SSE version of the MCP service is modified from the Filesystem MCP server

HTMLvault

AI tools (Claude, ChatGPT, Gemini, Grok, etc.) generate HTML constantly, from reports to landing pages to prototypes, but there's no easy way to share it or know if anyone looked. HTMLvault turns any HTML into a clean, t

Filesystem MCP Server for WSL

webconsulting

filesystem MCP server for accessing WSL distributions from Windows