MCP Workspace Server

A lightweight Python MCP server that gives AI agents safe, structured access to files inside a controlled local workspace.

Overview

AI agents often need access to project context stored in local files. Giving an agent unrestricted filesystem access introduces unnecessary security risk.

This project uses the Model Context Protocol (MCP) to expose a small set of controlled workspace tools while restricting access to a configured directory.

MCP Tools

The server exposes three tools:

list_workspace_files

Lists the files available inside the configured workspace.

read_text_file

Reads UTF-8 text files with configurable size limits.

search_text

Searches workspace documents and returns matching filenames, line numbers, and text.

Security

The server resolves requested paths against a defined workspace root and prevents path traversal outside that directory.

Additional safeguards include:

• Restricted workspace access
• Input validation
• File-size limits
• UTF-8 handling
• Path traversal protection
• Automated security tests

Project Structure

mcp-workspace-server/
├── src/
│   └── mcp_workspace_server/
│       ├── __init__.py
│       └── server.py
├── tests/
│   └── test_paths.py
├── workspace/
│   └── example.txt
├── pyproject.toml
└── README.md