Building Local File Systems with MCP and FastMCP

The Model Context Protocol (MCP) is the “USB-C for AI.” It allows any AI model to connect to any data source using a universal standard. To build with it, you need to understand three components:

• MCP Server: The “provider” that lives near your data (e.g., your local files).
• MCP Client: The “connector” inside an AI app (e.g., Claude or a custom script).
• FastMCP: The high-level Python framework that removes the complex protocol boilerplate.

1. The Server: Exposing the File System

We use FastMCP to define a Tool—an action the AI can take to list your Downloads folder.

File: filesystem_server.py

from fastmcp import FastMCP
from pathlib import Path

# 1. Initialize the FastMCP server
mcp = FastMCP("local-filesystem")
# Define the local path we want to explore
DOWNLOADS = Path.home() / "Downloads"
# 2. Define a Tool using the @mcp.tool() decorator
@mcp.tool()
def list_downloads() -> list[str]:
    """
    List file and folder names in the user's Downloads directory.
    The AI uses this docstring to understand when this tool is useful.
    """
    if not DOWNLOADS.exists():
        return ["Directory not found."]
    return sorted(p.name for p in DOWNLOADS.iterdir())
if __name__ == "__main__":
    mcp.run()

2. The Client: Accessing the Server

The client launches the server as a subprocess and manages the communication “handshake.”

File: mcp_client.py

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    # 1. Configuration: How to start your server
    server_params = StdioServerParameters(
        command="python3",
        args=["filesystem_server.py"], 
        env=None
    )
    # 2. Establish connection via STDIO
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            # 3. List tools to verify connection
            response = await session.list_tools()
            print("Server Tools Found:")
            for tool in response.tools:
                print(f"- {tool.name}: {tool.description}")
            # 4. Call the tool
            print("\nRequesting file list...")
            result = await session.call_tool("list_downloads", arguments={})

            for block in result.content:
                print(f"Files found:\n{block.text}")
if __name__ == "__main__":
    asyncio.run(main())

3. Instructions: How to Run and Test

A. Manual Execution (Client + Server)

Because MCP uses STDIO, you do not run the server and client in separate terminals. The client handles everything.

• Install dependencies:

pip install fastmcp mcp

• Run the client:

python3 mcp_client.py

B. Visual Debugging (The MCP Inspector)

The MCP Inspector is the “Postman for AI.” It allows you to visually test your tools in a browser without writing any client code. Before you run the inspector, you need to run the server script filesystem_server.py first.

Launch the Inspector:

• Run this command in your terminal:

npx -y @modelcontextprotocol/inspector python3 filesystem_server.py

Access the UI:

• The Inspector will automatically open your default browser to a URL like:
• [http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=xyz123](http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=xyz123)
• (The token is a security feature introduced in late 2025 to prevent unauthorized local access).
• Once the page loads, click on “Connect” to connect to your MCP server.
• Click on “Tools” in the sidebar menu.
• You will see **list_downloads** listed with the description from your Python docstring.
• Click “Run Tool” to see the real-time JSON response from your local filesystem.

Summary of Component Function

**FastMCP**The high-level "wrapper" that makes your functions speak the protocol.

**@mcp.tool()**Tells the AI: "You can run this function to change things or get data."

**StdioServerParameters**Tells the client exactly which command opens the bridge to the server.

**MCP Inspector**A visual dashboard for testing tools, resources, and prompts.