How to Intermediate · 3 min read

How to use filesystem MCP server

Q: How to use filesystem MCP server

Use the mcp Python SDK to create a filesystem MCP server by leveraging mcp.server.Server with the stdio_server transport. This enables AI agents to interact with local files and tools via the MCP protocol without network overhead.

Quick answer

Use the mcp Python SDK to create a filesystem MCP server by leveraging mcp.server.Server with the stdio_server transport. This enables AI agents to interact with local files and tools via the MCP protocol without network overhead.

PREREQUISITES

Python 3.8+
pip install mcp
Basic knowledge of Python async programming

Setup

Install the mcp Python package and prepare your environment for running a filesystem MCP server.

bash

pip install mcp

Step by step

This example shows how to create a simple filesystem MCP server using the stdio_server transport. The server listens on standard input/output, enabling local AI agents to connect and use filesystem tools.

python

import asyncio
from mcp.server import Server
from mcp.server.stdio import stdio_server

async def main():
    # Create the MCP server instance
    server = Server()

    # Run the server with stdio transport (filesystem mode)
    await stdio_server(server)

if __name__ == "__main__":
    asyncio.run(main())

Common variations

You can customize the MCP server by adding handlers for specific tools or resources. Also, you can run the server asynchronously in different environments or integrate with other transports besides stdio.

python

import asyncio
from mcp.server import Server
from mcp.server.stdio import stdio_server

async def custom_handler(request):
    # Implement custom logic for a tool or resource
    return {"result": "Handled by custom_handler"}

async def main():
    server = Server()
    # Register a custom handler for a tool named 'example_tool'
    server.register_handler("example_tool", custom_handler)
    await stdio_server(server)

if __name__ == "__main__":
    asyncio.run(main())

Troubleshooting

If the server does not start, ensure you are running the script in an environment that supports stdio communication (e.g., a terminal or a compatible container).
If you see JSON decode errors, verify that the client communicating with the MCP server follows the MCP protocol correctly.
Use logging or debug prints inside handlers to trace request handling issues.

✅

Key Takeaways

Use the mcp Python SDK and stdio_server to run a filesystem MCP server locally.
Register custom handlers on the MCP server to expose local tools and resources to AI agents.
Run the server asynchronously with asyncio for efficient event handling.
Ensure the client follows the MCP protocol to avoid communication errors.
Filesystem MCP servers enable AI agents to interact with local environments without network overhead.

Verified 2026-04

Verify ↗