Filesystem MCP server guide

Overview

The Filesystem MCP server provides access to the local filesystem, allowing AI agents to read and write files as part of their workflows. Use it to try ToolHive volume mounts with a local directory.

Run the server from its npm package, @modelcontextprotocol/server-filesystem. It is not included in the built-in ToolHive registry, so add it as a custom server. ToolHive builds a container from the package and runs it with your volume mounts and permissions.

note

Since most AI agent host applications like IDEs already have access to your working directory, this MCP server is primarily useful for access to files outside your working directory, headless environments where the host application does not provide filesystem access, or for demonstrating MCP capabilities.

Usage

UI

Add a custom local server with these settings:

• Protocol: npx
• Package name: @modelcontextprotocol/server-filesystem@2.0.1
• Name: filesystem
• Transport protocol: stdio
• Command arguments: /projects

In the Storage volumes section, add a local directory with /projects as its container path. Choose read-only or read-write access for the mount. If you choose a different container path, use that path in the command arguments too.

Security tip

Since the server does not require any network access, enable network isolation and do not add any hosts or ports to completely restrict its outbound network access.

Click Install server to build the container and start the server.

CLI

Mount a directory from the host filesystem to the MCP server and pass its container path as an allowed directory:

thv run --name filesystem --transport stdio --permission-profile none \
  --volume <HOST_DIRECTORY>:/projects \
  npx://@modelcontextprotocol/server-filesystem@2.0.1 -- /projects

Mount multiple files or directories by repeating the --volume flag. This example mounts a directory under /projects and a file under /data, and updates the command arguments accordingly:

thv run --name filesystem --transport stdio --permission-profile none \
  --volume <HOST_DIRECTORY>:/projects/dir1 \
  --volume <HOST_FILE>:/data/file.txt:ro \
  npx://@modelcontextprotocol/server-filesystem@2.0.1 -- /projects /data

tip

The --permission-profile none flag blocks outbound network access with ToolHive's network isolation, which is enabled by default. The --volume flags grant access to the specified host paths. Passing paths after -- tells the Filesystem MCP server which container directories it can access.

Kubernetes

Deploy the Filesystem MCP server with an existing persistent volume claim (PVC). First, build a container image from the npm package and push it to a registry your cluster can pull from. Replace <REGISTRY_NAMESPACE> with your GitHub Container Registry namespace:

thv build --tag "ghcr.io/<REGISTRY_NAMESPACE>/filesystem:2.0.1" \
  npx://@modelcontextprotocol/server-filesystem@2.0.1
docker push "ghcr.io/<REGISTRY_NAMESPACE>/filesystem:2.0.1"

Build on a machine with the same CPU architecture as your cluster's nodes. For a private image, configure image pull credentials.

Create filesystem.yaml with your image reference and PVC name. The PVC must exist in the toolhive-system namespace. This example mounts its contents at /projects and grants the server read-only access:

filesystem.yaml

apiVersion: toolhive.stacklok.dev/v1beta1
kind: MCPServer
metadata:
  name: filesystem
  namespace: toolhive-system
spec:
  image: ghcr.io/<REGISTRY_NAMESPACE>/filesystem:2.0.1
  transport: stdio
  proxyPort: 8080
  args:
    - /projects
  podTemplateSpec:
    spec:
      volumes:
        - name: filesystem-data
          persistentVolumeClaim:
            claimName: <PVC_NAME>
      containers:
        - name: mcp
          volumeMounts:
            - mountPath: /projects
              name: filesystem-data
              readOnly: true

Keep args aligned with mountPath if you change the container directory. Set readOnly: false to allow the server to write files to the volume.

Apply the manifest:

kubectl apply -f filesystem.yaml

Sample prompts

Here are some sample prompts you can use to interact with the Filesystem MCP server:

• "List all files in the /projects directory"
• "Read the contents of the file /projects/example.txt"
• "Write 'Hello, World!' to the file /projects/hello.txt"

Recommended practices

• Mount only the directories or files required for your AI agent's tasks to minimize resource usage and improve performance.
• Use read-only mounts for directories or files that do not need to be modified by the AI agent to prevent accidental changes.
• Enable network isolation in the UI or use --permission-profile none in the CLI to block outbound network access.

Next steps

• Connect an AI client and try the sample prompts. Writing files requires a read-write mount.
• Hide sensitive files within mounted directories.