# LanternFS - Secure Filesystem MCP

LanternFS is a remote filesystem MCP server that lets MCP clients such as ChatGPT access a controlled local directory.

It protects the remote MCP endpoint with OAuth, so exposing the server through ngrok does not mean that anyone who discovers the public URL can access the filesystem.

## Security model

```text
ChatGPT
   |
   | OAuth
   v
LanternFS
   |
   | Valid access token
   v
MCP endpoint
   |
   v
Filesystem tools
   |
   v
ALLOW_ROOTS
```

The password is used only during the OAuth authorization step. It is not used as the MCP access token and is never sent to the MCP tools.

## Features

- OAuth authorization for remote MCP clients.
- Designed for ChatGPT OAuth MCP connections.
- Password-only authentication or optional username and password.
- Authorization Code flow with S256 PKCE.
- Short-lived access tokens.
- Long-lived rotating refresh tokens.
- OAuth discovery and metadata through the MCP TypeScript SDK.
- Protected Streamable HTTP MCP endpoint.
- Configurable filesystem roots.
- ngrok HTTPS tunnel support.
- Secrets excluded from Git.

# Setup

## 1. Install Node.js

Use a current supported Node.js release.

```powershell
node --version
npm --version
```

## 2. Clone the repository

```powershell
git clone https://github.com/deviprasadshetty-dev/filesystem-mcp.git
cd filesystem-mcp
npm install
```

## 3. Create the environment file

Copy the example file:

```powershell
Copy-Item .env.example .env
```

Open it:

```powershell
notepad .env
```

## 4. Configure the filesystem root

The `ALLOW_ROOTS` setting controls which directories LanternFS can access.

For a safe setup, create a dedicated workspace:

```powershell
New-Item -ItemType Directory -Force D:\mcp-workspace
```

Then use:

```env
ALLOW_ROOTS=D:\mcp-workspace
```

Avoid exposing an entire drive unless you intentionally need it:

```env
ALLOW_ROOTS=D:\
```

OAuth controls who can connect, while `ALLOW_ROOTS` controls what an authorized client can access. You should use both.

## 5. Configure the OAuth password

Set a strong password in `.env`:

```env
MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password
```

The password must be at least 16 characters.

You can optionally configure a username:

```env
MCP_AUTH_USERNAME=deviprasad
MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password
```

If `MCP_AUTH_USERNAME` is empty, LanternFS uses a password-only login page.

If a username is configured, both username and password must match.

### How the password is used

You do not enter this password into ChatGPT's MCP settings.

When ChatGPT connects for the first time, it starts the OAuth authorization flow and opens the LanternFS login page.

Enter the same credentials that you configured in `.env`:

```text
Username: deviprasad
Password: ********

[ Authorize ]
```

After successful authorization, ChatGPT receives an OAuth authorization code and exchanges it for an access token and refresh token.

The password is not sent to `/mcp`.

## 6. Configure ngrok

LanternFS needs a public HTTPS URL so that ChatGPT can reach the MCP server.

The project can use an ngrok authtoken from either of these locations:

### Recommended: ngrok local configuration

Authenticate ngrok normally on your machine using the ngrok CLI and keep the token in ngrok's own configuration.

For example:

```powershell
ngrok config add-authtoken YOUR_NGROK_TOKEN
```

You do not need to put the ngrok token in `.env` when it is already configured locally.

### Alternative: `.token` file

LanternFS also supports a local `.token` file containing only the ngrok authtoken:

```text
YOUR_NGROK_TOKEN
```

The `.token` file is ignored by Git.

### Alternative: environment variable

You can also provide:

```env
NGROK_AUTHTOKEN=YOUR_NGROK_TOKEN
```

This is optional. Do not add it to `.env` unless you specifically want LanternFS to receive the token through the environment.

### Configure the ngrok domain

For a stable URL, set your ngrok domain:

```env
NGROK_DOMAIN=your-domain.ngrok-free.app
```

If `NGROK_DOMAIN` is empty, ngrok can use an ephemeral URL when supported by your account/configuration. A stable domain is recommended for a persistent ChatGPT MCP connection.

## 7. Example `.env`

A recommended setup looks like this:

```env
PORT=3000
ALLOW_ROOTS=D:\mcp-workspace
NGROK_DOMAIN=your-domain.ngrok-free.app

MCP_AUTH_USERNAME=deviprasad
MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password
```

Notice that `NGROK_AUTHTOKEN` is not required here when ngrok is already authenticated locally.

Never commit `.env` or `.token`.

# Run LanternFS

Check the project first:

```powershell
npm run build
npm test
```

Then start the server:

```powershell
npm start
```

The server starts the local MCP HTTP service and creates the ngrok HTTPS tunnel.

The console prints the public URL.

Keep the process running while ChatGPT needs the MCP connection.

## Recommended MCP client description

When adding LanternFS to an MCP client, use the following description so the client knows when it should use this server:

> LanternFS provides access to my local filesystem and project files. Use this MCP whenever a task involves files, folders, source code, repositories, documents, or other data that may exist on my local computer. Prefer LanternFS over guessing or asking me to paste file contents when the required files are available locally. Do not use it for information that does not require access to my local filesystem.

This description is intended for the MCP client's server description or tool-use guidance. It tells the client to prefer LanternFS for local-file tasks while avoiding unnecessary use for general knowledge or web-based tasks.
# Connect to ChatGPT

1. Start LanternFS with `npm start`.
2. Copy the public HTTPS MCP URL printed in the console.
3. Add a remote MCP connector in ChatGPT.
4. Select `OAuth` as the authentication method.
5. Enter the LanternFS MCP URL.
6. ChatGPT performs OAuth discovery.
7. Your browser opens the LanternFS authorization page.
8. Enter the username and password from `.env`.
9. Click `Authorize`.
10. ChatGPT completes the OAuth flow and connects to `/mcp`.

You should only need to enter the password when a new authorization is required.

## Persistent connection

LanternFS does not use a permanent access token.

The current implementation uses:

- Access tokens that expire after a short period.
- Long-lived refresh tokens that allow the client to obtain new access tokens.
- Refresh-token rotation when a refresh token is used.
- The configured password only for initial authorization.

This lets ChatGPT remain authorized without asking for the password every time while avoiding a permanent filesystem access token.

Deleting `.oauth-state.json` resets the locally stored OAuth state and requires clients to authorize again.

# OAuth endpoints

LanternFS uses the authorization interfaces provided by the installed MCP TypeScript SDK.

| Endpoint | Purpose |
| --- | --- |
| `/.well-known/oauth-protected-resource/mcp` | Protected Resource Metadata |
| `/.well-known/oauth-authorization-server` | OAuth Authorization Server Metadata |
| `/authorize` | OAuth authorization flow |
| `/token` | Authorization-code and refresh-token exchange |
| `/register` | OAuth client registration |
| `/revoke` | OAuth token revocation |
| `/mcp` | Protected MCP Streamable HTTP endpoint |

# Security recommendations

## Use a strong password

Use a unique random password of at least 16 characters.

For example, PowerShell can generate random bytes:

```powershell
[Convert]::ToBase64String((1..48 | ForEach-Object { Get-Random -Maximum 256 }))
```

Do not copy an example password into production.

## Restrict the filesystem

Prefer:

```env
ALLOW_ROOTS=D:\mcp-workspace
```

over:

```env
ALLOW_ROOTS=D:\
```

## Protect secrets

Never commit:

```text
.env
.token
.oauth-state.json
```

Before pushing changes:

```powershell
git status
git diff --cached
```

Never force-add these files.

## Protect your ngrok account

If an ngrok authtoken is exposed, rotate it through your ngrok account.

## Stop remote access when it is not needed

Stopping LanternFS stops its HTTP MCP endpoint and ngrok tunnel.

# Troubleshooting

## ChatGPT cannot complete OAuth discovery

Check that:

- LanternFS is running.
- ngrok is authenticated.
- The ngrok tunnel is active.
- The public URL uses HTTPS.
- `NGROK_DOMAIN` is correct if you configured one.

## The password is rejected

Check `.env` and restart LanternFS after changing it.

If `MCP_AUTH_USERNAME` is configured, both username and password must match.

## ChatGPT asks for authorization again

Check that `.oauth-state.json` still exists and has not been deleted or replaced.

A reset of the OAuth state intentionally requires authorization again.

## A filesystem path is unavailable

Check `ALLOW_ROOTS` and make sure the requested path is inside one of the configured roots.

# Development

```powershell
npm install
npm run build
npm test
npm start
```

`npm run build` performs a TypeScript type check.

`npm test` runs the filesystem self-check.

# References

LanternFS is built around the authorization architecture provided by the Model Context Protocol TypeScript SDK and the relevant OAuth standards.

- MCP Authorization specification: https://modelcontextprotocol.io/specification/draft/basic/authorization
- MCP TypeScript SDK: https://ts.sdk.modelcontextprotocol.io/
- MCP client registration guidance: https://blog.modelcontextprotocol.io/posts/client_registration/
- RFC 8414 - OAuth 2.0 Authorization Server Metadata: https://www.rfc-editor.org/rfc/rfc8414
- RFC 9728 - OAuth 2.0 Protected Resource Metadata: https://www.rfc-editor.org/rfc/rfc9728
- RFC 7636 - Proof Key for Code Exchange (PKCE): https://www.rfc-editor.org/rfc/rfc7636
- RFC 7009 - OAuth 2.0 Token Revocation: https://www.rfc-editor.org/rfc/rfc7009

MCP authorization behavior can evolve as the specification develops. Keep the MCP TypeScript SDK updated and review its authorization documentation when upgrading the project.

# License

Add a license before publishing LanternFS for broad reuse.