
Token-Aware Directory Explorer for Large Language Models (LLMs).
Token-Aware Directory Explorer for Large Language Models (LLMs).
·
Token-Aware Directory Explorer for Large Language Models (LLMs).
A Model Context Protocol (MCP) server that helps LLMs efficiently explore and understand codebases and directory structures.
TokenScope provides intelligent directory structure analysis and token-aware file content exploration designed for LLMs like Claude. It helps LLMs understand codebases by:
TokenScope provides just three core tools:
explore_directory - Scan and understand directory structuresview_content - Access file contents with token awarenessgenerate_report - Create comprehensive reports (with option to save to file)This is the recommended method for most users who just want to use TokenScope:
# Install from PyPI using uv (recommended)
uv pip install tokenscopeThe --base-path argument is mandatory for security reasons. It restricts all file operations to the specified directory.
# Run using the installed package
uv run --with tokenscope tokenscope --base-path /path/to/allowed/directoryLocate Claude Desktop's configuration file (typically ~/.config/claude/config.json)
Add TokenScope to the mcpServers section:
"mcpServers": {
"TokenScope": {
"command": "uv",
"args": [
"run",
"--with",
"tokenscope",
"tokenscope",
"--base-path",
"/your/secure/base/path"
]
}
}Replace /your/secure/base/path with the directory you want to restrict operations to
Save the configuration file and restart Claude Desktop
The --base-path argument is required for security (it restricts file operations to the specified directory):
tokenscope --base-path /path/to/allowed/directoryTokenScope includes a test mode for trying out tools directly:
# Test directory exploration
tokenscope --base-path /path/to/allowed/directory --test "explore:/path/to/directory"
# Test with custom ignore patterns
tokenscope --base-path /path/to/allowed/directory --test "explore:/path/to/directory?ignore=cache,*.log,tmp/&gitignore=false"
# Test file viewing
tokenscope --base-path /path/to/allowed/directory --test "view:/path/to/file"
# Test report generation
tokenscope --base-path /path/to/allowed/directory --test "report:/path/to/directory"
# Test report generation with file output and custom ignore patterns
tokenscope --base-path /path/to/allowed/directory --test "report:/path/to/directory?ignore=*.bak,temp/ > /path/to/output.md"Here are some examples of how to use TokenScope with Claude:
Could you explore my project directory at /path/to/project and tell me about its structure?Can you show me the content of the file at /path/to/file.py?Please generate a comprehensive report about my project at /path/to/project and save it to /path/to/report.mdTokenScope now provides two levels of directory information:
This dual approach ensures that even for massive directories (with thousands or millions of files), you'll get accurate information about the total number of files, directories, and disk usage. This is especially valuable when working with large codebases where a complete directory listing would exceed token limits.
QUICK SCAN STATISTICS (files visible in tree):
Files shown in tree: 47
Directories shown in tree: 16
Size shown in tree: 185.9 MB
FULL DIRECTORY STATISTICS (all files):
Total files: 16,059
Total directories: 8
Total disk size: 2.1 GBTokenScope automatically filters out common directories and files that typically don't contribute to understanding a codebase:
.git/, .venv/, venv/, __pycache__/, node_modules/, build/, dist/, etc.ignore_patterns parameterThis functionality helps prevent token waste on irrelevant files and directories like:
node_modules, virtual environments)# Ignore specific patterns
tokenscope --base-path /path --test "explore:/code?ignore=*.log,temp/"
# Disable .gitignore processing
tokenscope --base-path /path --test "explore:/code?gitignore=false"
# Both together
tokenscope --base-path /path --test "explore:/code?ignore=*.tmp&gitignore=false"TokenScope includes important security features:
This project is licensed under the MIT License - see the LICENSE file for details.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add TokenScope -- uv run --with tokenscope tokenscope --base-path /your/secure/base/path{
"mcpServers": {
"TokenScope": {
"args": [
"run",
"--with",
"tokenscope",
"tokenscope",
"--base-path",
"/your/secure/base/path"
],
"command": "uv"
}
}
}code --add-mcp '{"name":"TokenScope","args":["run","--with","tokenscope","tokenscope","--base-path","/your/secure/base/path"],"command":"uv"}'[mcp_servers.TokenScope]
command = "uv"
args = ["run", "--with", "tokenscope", "tokenscope", "--base-path", "/your/secure/base/path"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/tokenscope to learn what the "TokenScope" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
uv pip install tokenscopeThis server runs locally, so we can't read its tool list over the web yet.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/tokenscope)Nothing comparable is listed yet.
No tagged releases on record.
Connect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "tokenscope" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.