# Filesystem MCP server guide

## Overview[​](#overview "Direct link to Overview")

The [Filesystem MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) 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.

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[​](#usage "Direct link to Usage")

* UI
* CLI
* Kubernetes

Select the `filesystem` MCP server in the ToolHive registry.

In the **Storage volumes** section, [add a local directory](/toolhive/guides-ui/configure-mcp-servers.md#storage-volumes) 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**](/toolhive/guides-ui/network-isolation.md) and do not add any hosts or ports to completely restrict its outbound network access.

Click **Install server** to start the server.

[Mount a directory](/toolhive/guides-cli/filesystem-access.md) from the host filesystem to the MCP server and pass its container path as an allowed directory:

```
thv run --permission-profile none \

  --volume <HOST_DIRECTORY>:/projects \

  filesystem -- /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 --permission-profile none \

  --volume <HOST_DIRECTORY>:/projects/dir1 \

  --volume <HOST_FILE>:/data/file.txt:ro \

  filesystem -- /projects /data
```

tip

The `--permission-profile none` flag blocks outbound network access with ToolHive's [network isolation](/toolhive/guides-cli/network-isolation.md), 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.

Deploy the Filesystem MCP server with an existing persistent volume claim (PVC). Create `filesystem.yaml` with your 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/stacklok/dockyard/npx/server-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[​](#sample-prompts "Direct link to 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[​](#recommended-practices "Direct link to 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[​](#next-steps "Direct link to Next steps")

* [Connect an AI client](/toolhive/guides-cli/client-configuration.md) and try the sample prompts. Writing files requires a read-write mount.
* [Hide sensitive files](/toolhive/guides-cli/thvignore.md) within mounted directories.