# Mcpfs

> Mount MCP servers as a filesystem. Plan 9 for the agent era.

- **Type:** MCP server
- **Install:** `agentstack add mcp-airshelf-mcpfs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [airshelf](https://agentstack.voostack.com/s/airshelf)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [airshelf](https://github.com/airshelf)
- **Source:** https://github.com/airshelf/mcpfs

## Install

```sh
agentstack add mcp-airshelf-mcpfs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcpfs

Mount any MCP server as a filesystem. Reads via `cat`, writes via CLI.

## How it works

mcpfs connects to any MCP server (stdio or HTTP), classifies its tools into reads and writes, and exposes reads as files:

```
 Agent / Shell                    mcpfs (FUSE)                  Any MCP Server
┌─────────────┐              ┌──────────────────┐         ┌──────────────────┐
│ ls /mnt/...  │─── readdir ─▶│ tools/list →     │         │ PostHog, Stripe, │
│ cat file.json│─── read() ──▶│ classify → tree  │── RPC ─▶│ GitHub, Linear,  │
│ jq '.name'  │◀── bytes ───│ tools/call       │◀─ JSON ─│ or anything      │
└─────────────┘              └──────────────────┘         └──────────────────┘

 Agent / Shell                    mcpfs tool CLI
┌─────────────┐              ┌──────────────────┐
│ mcpfs tool   │── flags ──▶│ parse CLI flags  │── RPC ─▶ MCP Server
│ posthog      │              │ tools/call       │
│ create-flag  │◀── JSON ───│                  │◀─ JSON ─
└─────────────┘              └──────────────────┘
```

**Classification rules:**
- `list_*`, `get_all_*`, no required params → **file** (`dashboards.json`)
- `get_*`, `retrieve_*`, has required params → **directory** (lookup by ID)
- `create_*`, `update_*`, `delete_*` → **CLI only** (`mcpfs tool`)
- `search_*`, `query_*` → **CLI only** (`mcpfs tool`)

Resources (if the server has them) are also mounted as files.

## Quick start

```bash
# Build and install
go install github.com/airshelf/mcpfs/cmd/mcpfs@latest

# Auto-discover Claude Code plugins and mount in project dir
cd ~/src/myproject
mcpfs auto                    # mounts to .mcpfs/ in cwd
mcpfs auto --mount /mnt/mcpfs # or specify a custom mount dir

# Mount a single server
mcpfs .mcpfs/posthog --http https://mcp.posthog.com/mcp --auth "Bearer $POSTHOG_API_KEY"
mcpfs .mcpfs/stripe -- npx -y @stripe/mcp

# Read
ls .mcpfs/posthog/
cat .mcpfs/posthog/dashboards.json
cat .mcpfs/stripe/balance.json

# Write (CLI)
mcpfs tool posthog create-feature-flag --key my-flag --name "My Flag"
mcpfs tool stripe create_customer --name "Acme Corp" --email acme@example.com

# List all tools for a server
mcpfs tool posthog
mcpfs tool stripe

# Unmount
fusermount -u .mcpfs/posthog
```

## Config file

Mount multiple servers from a single config (`~/.config/mcpfs/servers.json`):

```json
{
  "posthog": {
    "type": "http",
    "url": "https://mcp.posthog.com/mcp",
    "headers": {"Authorization": "Bearer ${POSTHOG_API_KEY}"}
  },
  "stripe": {
    "command": "npx",
    "args": ["-y", "@stripe/mcp"],
    "env": {"STRIPE_SECRET_KEY": "${STRIPE_API_KEY}"}
  },
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"}
  }
}
```

Environment variables (`${VAR}`) are interpolated from the process environment or from `~/.config/mcpfs/env`.

```bash
# Mount all to .mcpfs/ in cwd
mcpfs --config ~/.config/mcpfs/servers.json

# Mount to custom dir
mcpfs --config ~/.config/mcpfs/servers.json --mount /mnt/mcpfs
```

## Auto-discover Claude Code plugins

If you use Claude Code, `mcpfs auto` discovers all installed MCP plugins and mounts them in your project:

```bash
cd ~/src/myproject
mcpfs auto           # discover + mount to .mcpfs/
mcpfs auto --json    # print discovered config (dry run)
```

Mounts to `.mcpfs/` in the current directory. Reads `.env.local` and `.env` from cwd for project-specific credentials (e.g., different Vercel teams, PostHog projects per repo).

It reads from all Claude Code config sources:
- `~/.claude.json` → `mcpServers` — global user-configured servers
- `~/.claude/plugins/` — installed plugins and their `.mcp.json`
- `~/.claude/settings.json` → `enabledPlugins` — also scans cache for these
- `~/.claude/.credentials.json` — OAuth tokens (Notion, etc.)
- `~/.config/mcpfs/servers.json` — additional user-defined servers
- `~/.config/mcpfs/env` — fallback env vars (API keys)
- `gh auth token` — GitHub token fallback

Non-data plugins (playwright, serena, context7) are skipped automatically.

## Cross-service composition

```bash
# Business dashboard
printf "%-20s %s\n" "Stripe balance" "$(cat .mcpfs/stripe/balance.json | jq -r '.available[] | "\(.currency) \(.amount / 100)"')"
printf "%-20s %s\n" "Active subs" "$(cat .mcpfs/stripe/subscriptions.json | jq '[.[] | select(.status=="active")] | length')"
printf "%-20s %s\n" "PH dashboards" "$(cat .mcpfs/posthog/dashboards.json | jq length)"

# Find paying customers with no analytics activity
comm -23 \
  ` to list write/query tools with `--help`
- `mcpfs tool   --flag value` for writes
- All tool output goes to stdout (JSON), hints go to stderr
- Exit codes: 0 success, 1 error

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [airshelf](https://github.com/airshelf)
- **Source:** [airshelf/mcpfs](https://github.com/airshelf/mcpfs)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-airshelf-mcpfs
- Seller: https://agentstack.voostack.com/s/airshelf
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.