peekaboo-mcp

Minimal Model Context Protocol (MCP) server for read-only file system access.

Claude Code (or any AI coding agent) often makes broader changes than intended. You ask it to fix a simple bug, and it refactors half your codebase. This happens because Claude Code has full read/write access to everything in your project directory.

Peekaboo-mcp lets you isolate what Claude Code (or any AI agent) can modify while still giving it visibility into your entire codebase. Simply:
- Open your editor in a small, dedicated workspace folder
- Let peekaboo-mcp provide read-only access to your actual project.

Now Claude Code can see all the context it needs but can only modify files in your controlled workspace.
-

Install peekaboo-mcp in your project root:

cd /path/to/your/project npm install peekaboo-mcp

For Claude Desktop:Add to~/Library/Application Support/Claude/claude_desktop_config.json(Mac):

{ "mcpServers": { "peekaboo": { "command": "npx", "args": ["peekaboo-mcp"], "cwd": "/path/to/your/project" } } }

# One-time setup: Navigate to your project and add peekaboo cd /path/to/your/project claude mcp add peekaboo npx peekaboo-mcp # From now on, just start Claude Code claude # Claude automatically launches peekaboo when it starts! # Optional: Check MCP server status > /mcp # Should show: peekaboo: connected ✓

For Cursor.AI:Create.cursor/mcp.jsonin your home directory or project:

{ "mcpServers": { "peekaboo": { "command": "npx", "args": ["-y", "peekaboo-mcp"], "cwd": "/path/to/your/project" } } }

- Open Command Palette (Ctrl/Cmd + Shift + P)
- Search for "Cursor Settings"
- Navigate to MCP Servers section
- Add peekaboo-mcp with the project path

Important: You don't need to manually launch peekaboo! Claude Desktop, Claude Code, and Cursor all automatically start the MCP server when they need it.

Open ONLY the folder you want AI to work on:

Instead of opening your entire project, open just the specific folder you want modified:

# Example: You want AI to work on your React components cursor /path/to/your/project/src/components # Or: You want AI to refactor your API routes cursor /path/to/your/project/api/routes

- ✅ Read your ENTIRE project (understands full context)
- ✅ Only modify files in/src/components(or whatever folder you opened)
- ❌ Cannot touch files outside the opened folder

- List directory contents recursively by default
- Read file contents with MIME type detection
- Search files by name pattern (glob support)
- Search content within files
- Strict read-only access (no write/edit/delete operations)
- Path traversal protection
- Automatic project root detection (accesses only the project where installed)
- Configurable recursion depth
- Resource management (timeouts, file size limits)
- Comprehensive test coverage

# Run from your project (automatically detects project root) npx peekaboo-mcp # Disable recursive listing PEEKABOO_RECURSIVE=false npx peekaboo-mcp # Set custom max depth (default: 10) PEEKABOO_MAX_DEPTH=5 npx peekaboo-mcp

Note: peekaboo-mcp automatically detects and uses the project root where it's installed. It cannot access files outside of this project for security reasons.

import { createPeekabooServer, findProjectRoot } from 'peekaboo-mcp'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; // Automatically detect project root const rootDir = findProjectRoot(); // Default: recursive listing enabled, max depth 10 const server = createPeekabooServer(rootDir); // Or with custom config const server = createPeekabooServer(rootDir, { recursive: false, // Disable recursive listing maxDepth: 5, // Limit recursion depth timeout: 60000, // 60 second timeout (default: 30s) maxFileSize: 5  1024  1024, // 5MB max file size (default: 10MB) maxTotalSize: 50  1024  1024 // 50MB max total size (default: 100MB) }); const transport = new StdioServerTransport(); await server.connect(transport);

{ "mcpServers": { "peekaboo": { "command": "npx", "args": ["peekaboo-mcp"] } } }

- All file access is strictly read-only
- Automatic project root detection prevents access outside the installed project
- Path traversal above the project root is blocked
- No write, edit, or delete operations are supported
- No user-configurable root directory (prevents manipulation by LLMs or malicious actors)
- List Resources: Returns all files and directories from the root (recursive by default)
- Read Resource: Returns the content of a specific file

Resources are accessed viafile://URIs relative to the configured root.
-

search_path: Search for files and directories by name pattern

- Supports wildcards:(any characters),(any directories),?(single character)
- Examples:.ts,src//.js,test-?.md

An MCP server for manipulating and managing Excel files.