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

pdfAssistant MCP Server

pdfassistant-ai

Official MCP server for pdfAssistant. Connect Claude, ChatGPT, or any MCP client to perform professional PDF processing like OCR, permanent redactions, secure encryption, format conversions, and 40+ advanced operations p

PDF Extraction MCP Server (Claude Code Fork)

xraywu

MCP server to extract contents from a PDF file

mcp-rquest

xxxbrian

A MCP server providing realistic browser-like HTTP request capabilities with accurate TLS/JA3/JA4 fingerprints for bypassing anti-bot measures. It also supports converting PDF and HTML documents to Markdown for easier processing by LLMs.

Filesystem

chrisdoc

Manage your Hevy workouts, routines, folders, and exercise templates. Create and update sessions faster, organize plans, and search exercises to build workouts quickly. Stay synced with changes so your training log is always up to date.

310

MCP File System Server

MarcusJellinghaus

MCP Workspace Server: A secure Model Context Protocol server providing file, git, and GitHub tools for AI assistants within a sandboxed project directory.