dotlink MCP server
Commit Nov 15, 2026Enables ChatGPT and Claude to securely access local files, run shell commands, and use local tools through an outbound secure tunnel.
Also known as abird-ai/dotlink
- Stars
- 7
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is dotlink MCP?
dotlink enables ChatGPT and Claude to securely access local files, run shell commands, and use local tools through an outbound secure tunnel.
Summary generated from the project's README
About dotlink MCP server
Developers can connect ChatGPT and Claude to their local machines to interact with files and run commands through a secure outbound tunnel. By running a single binary, you can expose specific projects or tools to remote AI clients without needing to install a desktop application or configure SSH. This setup allows for direct file editing, Git operations, and script execution while keeping the MCP server local to your hardware.
Security is managed through a local permission engine where the launch directory is read-only by default. You must explicitly grant access for write operations, shell commands, or network connectivity using specific flags. On Linux, shell execution is protected by a Bubblewrap sandbox. The system supports various connection methods including an OpenAI Secure MCP Tunnel for ChatGPT Web, and HTTP with ngrok and OAuth protection for Claude.ai or other remote clients.
What you can do with it
- 1Direct local file manipulationAsk an AI client to read, edit, or patch files directly within your local project directory.
- 2Remote machine managementProvide ChatGPT access to multiple computers by running the server on each machine to expose specific capabilities.
- 3Securely exposing local toolsRun shell commands and build processes through a sandboxed environment on Linux.
- 4Local development with stdioUse the server as a local sandboxed MCP server for clients that launch processes as children.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
NGROK_AUTHTOKEN
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableabird-ai/dotlink is public and reachablegithub.com/abird-ai/dotlink ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/abird-ai/dotlink ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubdotlink
Simply @dotlink anywhere in ChatGPT — chat, space, or your dot to work with files on your machine, use local tools and projects you exposed — securely, from a single binary.
A single lightweight binary with an MCP server, OpenAI tunnel transport, permission engine, profiles, activity logging, and a full Bubblewrap sandbox on Linux — no UI, no third-party relay, guided setup.
- Let your ChatGPT Web and your dot work directly on your computer through controlled, fine-grained access: read and edit files, run Git, build, test, execute scripts, and use only the tools you explicitly expose.
- Give ChatGPT controlled access to several machines without installing the ChatGPT desktop app or provisioning SSH: run dotlink on each machine and expose only the projects, files, and capabilities you choose.
- Use local data without the upload/download loop: analyze files, build reports or slide decks, and work with artifacts directly from your machine.
- Use ChatGPT as a practical fallback when Codex usage is unavailable or exhausted: reconnect to the same project state and keep going.
When your machine is offline, keep planning against context already in ChatGPT; reconnect later and let ChatGPT re-read the live project before continuing.
For ChatGPT, dotlink opens an outbound OpenAI Secure MCP Tunnel directly from your machine to OpenAI. Your MCP server stays local: no public inbound port, no third-party relay.
Supports Claude.ai and other remote MCP clients over HTTP/ngrok, plus local MCP clients over stdio or loopback HTTP. Every transport uses the same local permission policy.
Security is local and opt-in: the launch directory is read-only by default; write, shell, network, extra paths, caches, and public HTTP are separate grants. Linux shell execution is Bubblewrap-sandboxed by default.
Quick start
Install
Linux x86_64/ARM64 or macOS Apple Silicon:
curl -fsSL https://raw.githubusercontent.com/abird-ai/dotlink/main/install.sh | sh
Windows x86_64/ARM64 PowerShell:
irm https://raw.githubusercontent.com/abird-ai/dotlink/main/install.ps1 | iex
Both installers download the latest published GitHub Release by default, select the correct architecture internally, verify its SHA-256, and require the downloaded executable to identify itself as the requested dotlink version before replacement. The command you run is always simply dotlink; architecture suffixes exist only on the release assets (dotlink.exe is the Windows file on disk). Re-run the same install command at any time to update; if the installed binary already matches the latest release, it is left unchanged.
Or build with Nix/Cargo; see Build below.
Setup
dotlink --setup
cd ~/src/my-project
dotlink
Setup is transactional: choose 0, none, or cancel to exit successfully without writing anything. Re-running --setup on an existing profile uses its current values as defaults; secret prompts show only [existing key], and blank input keeps the stored key.
Compatible older profile schemas are migrated forward automatically in memory. In particular, schema v9 loads directly as v10 because the v10 fields are additive/defaulted; the profile is written as the current schema the next time it is edited or saved. Newer schemas are never guessed, and older configs that need an explicit security decision—such as newly protected public ingress—fail with the specific setting that must be updated.
The launch directory is readable by default. Add capabilities only when needed:
dotlink --allow-rw
dotlink --allow-rw --allow-shell
dotlink --allow-rw --allow-shell --allow-network
Manage profiles
dotlink profile list
dotlink profile show work
dotlink profile create work
dotlink profile edit work
dotlink profile delete work
dotlink profile allow work rw /shared
dotlink profile deny work read /secret
dotlink profile remove-allow work rw /shared
dotlink profile remove-deny work read /secret
dotlink profile enable work shell
dotlink profile enable work network
dotlink profile disable work network
Use default as the profile name to manage the unnamed default profile. Persisted settings can be toggled with profile enable/disable: openai, stdio, http, http-ephemeral-url, ngrok, ngrok-ephemeral-url, oauth, default-allow, shell, and network. Enabling a dependent setting automatically enables its prerequisite (network → shell, ngrok → http, oauth → http); disabling a parent safely disables its dependents. Enabling ngrok or oauth requires an owner OAuth credential; use dotlink profile edit <name> when one still needs to be configured.
What it looks like
Default runs are quiet. Add -v to see tool activity:
$ dotlink -v -p aw
dotlink v0.14.3
────────────────────────────────────────────────────────
• Profile aw
• Transports openai
• Tunnel tunnel_…
• Access read:2 write:1 deny-read:0 deny-write:0 caches:0 + shell
• Sandbox Bubblewrap
• Network enabled
• Logging TOOL
OpenAI Secure MCP Tunnel connecting…
Keys Ctrl-C: exit · Ctrl-R: restart · v: verbosity · V: full commands
✓ Connected — ready
[10:59:19.184] TOOL read → p="./.agents/plans/TODO.md"
[10:59:19.194] TOOL read ← ok 9ms
-v starts with TOOL activity; -vv adds REQ diagnostics. Interactive runs support v to cycle verbosity, V to toggle full command logging while TOOL logging is active, Ctrl+R to reload the runtime, and Ctrl+C to exit. stdio keeps stdin protocol-clean. File contents, binary payloads, Runtime keys, and raw request bodies are not intentionally logged.
Connect dotlink to ChatGPT
1. Start dotlink
Run setup once and select OpenAI Tunnel:
dotlink --setup
Then start dotlink from the project you want ChatGPT to access:
cd ~/src/my-project
dotlink
Copy the printed tunnel_... ID and keep dotlink running.
2. Add it to ChatGPT
- Open https://chatgpt.com/plugins.
- Select Add → Create MCP App.
- Name it abird dotlink and optionally add a short description.
- Under Connection, choose Tunnel.
- Paste the
tunnel_...ID printed by dotlink. - Accept the custom-MCP warning and create the MCP app.
- In a ChatGPT conversation, open the tools menu, enable abird dotlink, and ask normally.
After that, simply mention @dotlink in ChatGPT Web — in a normal chat, a Space, or your dot — whenever you want to work with the files and projects that machine has exposed.
For several computers, run dotlink on each machine and add each tunnel as its own MCP App. Name the connections by machine or project if useful. ChatGPT can then reach each machine under its own local permission policy, with no ChatGPT desktop app required on those machines.
If Create MCP App is unavailable, enable Developer mode under Settings → Security and login first.
The tools ChatGPT discovers follow dotlink's local permissions:
read-only ls, grep, read, bread
write + write, bwrite
read + write + edit, patch, bedit
shell + bash/powershell + durable job controls
Never paste a Runtime or Admin API key into ChatGPT. ChatGPT only needs the tunnel_... ID.
If the tunnel is not found, verify that dotlink shows ✓ Connected — ready, the tunnel belongs to the current ChatGPT workspace, and the Runtime API key has Tunnels Read + Use.
Detailed reference: docs/CHATGPT_PLUGIN.md.
Connect dotlink to Claude.ai
Claude.ai custom connectors connect from Anthropic's cloud, so a loopback URL cannot be used directly. dotlink can publish its Streamable HTTP server through ngrok and automatically protects the public endpoint with OAuth.
1. Configure HTTP + ngrok
Run setup, select HTTP, then enable the public ngrok endpoint:
dotlink --setup
Setup asks for one owner password the first time OAuth is needed. The password itself is never stored; dotlink persists only an Argon2id hash in its private state directory.
Set your ngrok account token and start dotlink:
export NGROK_AUTHTOKEN='...'
dotlink
You can also add HTTP/ngrok for one run:
dotlink --http --ngrok
dotlink prints the public MCP resource and OAuth issuer:
✓ ngrok MCP: https://my-dotlink.ngrok.app/mcp
✓ OAuth: https://my-dotlink.ngrok.app (resource https://my-dotlink.ngrok.app/mcp)
For a durable connector, reserve an ngrok domain and persist it during setup or use:
dotlink --http --ngrok --ngrok-domain=my-dotlink.ngrok.app
Keep the normal stable /mcp path for durable OAuth. An automatic ngrok hostname or --ngrok-ephemeral-url changes the OAuth resource identity when the URL changes, so the remote client must be re-linked.
2. Add it to Claude.ai
- Open Customize → Connectors.
- Select + → Add custom connector.
- Name it abird dotlink.
- Paste the printed ngrok MCP URL.
- Connect it.
- When OAuth opens, review the client ID, redirect URI, resource, and scope, then enter your dotlink owner password and approve access.
The client receives short-lived bearer tokens plus rotating refresh tokens; reconnects do not require re-entering the owner password while the durable refresh grant remains valid.
For Team/Enterprise organizations, an owner may need to register the custom connector in organization connector settings before members can enable it.
3. Enable it in a conversation
In Claude, use the + menu in the composer, open Connectors, and enable abird dotlink. Claude sees only the MCP tools allowed by the running dotlink profile.
Connect other remote MCP clients
Any remote client that supports MCP Streamable HTTP + OAuth 2.1 can use the same endpoint. dotlink exposes Protected Resource Metadata, OAuth Authorization Server Metadata, authorization-code + PKCE S256, CIMD, DCR fallback, rotating refresh tokens, and revocation.
For a reverse proxy other than ngrok, protect local HTTP with OAuth and tell dotlink its canonical external origin:
dotlink --http --oauth --http-bind=127.0.0.1:3000 \
--public-url=https://mcp.example.com
Never derive the OAuth issuer from proxy/Host headers; --public-url is the explicit trust boundary.
Public ngrok ingress is OAuth-protected by default. Direct non-loopback HTTP binds are also refused unless OAuth is enabled with an explicit HTTPS public origin. The only way to intentionally expose either form of public ingress without application-layer authentication is the explicit one-run escape hatch:
dotlink --http --ngrok --allow-public-no-auth
# or, for an intentionally unauthenticated LAN listener:
dotlink --http --http-bind=192.168.1.50:3000 --allow-public-no-auth
For LAN use, replace the example address with the machine's actual interface address; wildcard binds do not identify a concrete public Host authority. This mode exposes every MCP capability granted to the process to anyone who can reach the endpoint and is not recommended.
Use dotlink as a local sandboxed MCP server
For local MCP clients, no public tunnel is required.
stdio
Use stdio when the client launches MCP servers as child processes:
dotlink --stdio --allow-rw --allow-shell
Typical MCP client configuration:
{
"mcpServers": {
"dotlink": {
"command": "dotlink",
"args": ["--stdio", "--allow-rw", "--allow-shell"]
}
}
}
On Linux the shell is still Bubblewrap-sandboxed.
Local Streamable HTTP
For local clients that support Streamable HTTP:
dotlink --http --allow-rw --allow-shell
Connect to:
http://127.0.0.1:3000/mcp
This stays loopback-only unless you explicitly change --http-bind. Loopback HTTP is unauthenticated by default; add --oauth to protect it. When putting local HTTP behind a reverse proxy, also provide the canonical external origin with --public-url=https://....
Architecture and security
One LocalMachine policy core serves every transport:
ChatGPT ── OpenAI Secure MCP Tunnel ─┐
Claude.ai / remote MCP ── HTTP/ngrok ├─ LocalMachine ─ policy-aware tools ─ host
Local MCP clients ── stdio/HTTP ─────┘
├─ Rust filesystem tools
└─ shell → Bubblewrap on Linux
Profiles persist transports, path grants/denies, shell/network policy, HTTP/ngrok options, and approved developer caches. Enabled profile transports start automatically; CLI flags add or suppress local transports for one run.
Default security
launch-directory read ON
launch-directory write OFF
extra filesystem paths OFF
shell OFF
shell network OFF
shared developer caches OFF
KVM / GPU devices OFF
public HTTP ingress OFF
unsandboxed host mode OFF
Capabilities are independent: --allow-read, --allow-write, --allow-rw, --allow-shell, and --allow-network. CLI grants compose with the selected profile; denies always win. --allow-rw=/ grants filesystem RW only. Full unsandboxed host authority is the explicit --unrestricted mode; the legacy --allow-all --no-sandbox pair remains equivalent.
Filesystem policy
ls / grep / read / bread require read
write / bwrite require write
edit / patch / bedit require read + write
Targets are canonicalized before checks; create targets canonicalize their nearest existing ancestor, preventing symlink escapes. The advertised MCP tool list is permission-aware, so unavailable write/shell tools are omitted rather than merely rejected later. Detailed tool, paging, mutation, replay, and platform invariants live in Architecture and Security.
Linux sandbox
With --allow-shell, Bash runs inside Bubblewrap by default. Read grants mount RO, read+write grants mount RW, denied paths are masked or downgraded, networking is isolated unless --allow-network is granted, credentials stay hidden, and only approved developer caches/Nix runtime paths are exposed. See docs/SECURITY.md for the full sandbox model.
Full unsandboxed access
Unsandboxed shell execution inherently has the OS user's filesystem and network authority, so dotlink exposes one explicit full-host escape hatch rather than several partial "dangerous" flags:
dotlink --unrestricted
This grants:
filesystem read+write /
shell enabled
network enabled
sandbox disabled
For unrestricted filesystem access without removing the Linux sandbox, use the ordinary path model instead:
dotlink --allow-rw=/
Then add --allow-shell and/or --allow-network separately if needed. On Linux, those capabilities remain Bubblewrap-sandboxed unless --unrestricted is explicitly selected.
OpenAI Secure MCP Tunnel
This setup is shown only when OpenAI transport is enabled.
Setup asks for:
- a Runtime API key with Tunnels Read + Use;
- a tunnel:
- No Admin key in dotlink: create one at https://platform.openai.com/settings/organization/tunnels, then paste its existing
tunnel_...ID; - Create from dotlink: type
newand provide a one-time Admin API key with Tunnels Manage;
- No Admin key in dotlink: create one at https://platform.openai.com/settings/organization/tunnels, then paste its existing
- a ChatGPT Workspace ID or OpenAI Organization ID only when dotlink creates the tunnel.
The one-time Admin key is never persisted.
The Runtime key is stored separately from JSONC config and follows the selected profile:
~/.config/abird/dotlink/runtime.key
~/.config/abird/dotlink/runtime.work.key
DOTLINK_CONFIG may move the JSONC file, but Runtime keys always stay in dotlink's private XDG directory above. The active config and credential directory are control-plane state and are not exposed through dotlink's MCP/filesystem/shell surface.
When OpenAI transport is disabled for a profile, that profile does not require a runtime key.
Shell execution is durable: if a bash/powershell call cannot return its complete result inside the tunnel response window, the same execution continues behind a job/task handle instead of being restarted. The shell tool surface includes explicit background start, status, output paging, acknowledgement, and cancellation controls. See Architecture for the transport and replay model.
Automatic tunnel recovery
Transient OpenAI poll failures retry with backoff. Normal warnings stay concise; full transport diagnostics are available with -vv.
After 10 transient poll failures without an accepted poll, dotlink rebuilds the runtime from the current profile and policy. Repeated runtime restarts back off from 1 second to a 30-second cap and reset after a healthy connection; persistent tunnel/key rejection is given a short recovery window before operator action is required.
Useful locations:
- Tunnels: https://platform.openai.com/settings/organization/tunnels
- Runtime API keys: https://platform.openai.com/settings/organization/api-keys
- Admin API keys: https://platform.openai.com/settings/organization/admin-keys
- ChatGPT Workspace ID: https://chatgpt.com/admin
- OpenAI Organization ID: https://platform.openai.com/settings/organization/general
Logging
Logging is quiet by default:
default no TOOL / REQ activity
-v TOOL activity
-vv TOOL + transport/request REQ diagnostics
-q suppress TOOL activity (useful with -vv for REQ-only)
Example with -v:
[01:06:47.410] TOOL read → p="./README.md" limit=1
[01:06:47.411] TOOL read ← ok 1ms
With -vv, transport diagnostics are added:
[01:06:47.426] REQ stdio → initialize
[01:06:47.427] REQ stdio → tools/call
TOOL logs include bounded command previews plus complete path labels, methods, status, and latency; file contents, binary payloads, Runtime keys, and raw request bodies are not intentionally logged. Interactive V removes the command-preview cap while TOOL logging is active, so use it only when command text is safe to retain.
Color is automatic on interactive human-facing output, including --help. Override with --color=always, --color=never, or --color=auto. stdio keeps stdin protocol-clean and exposes only Ctrl+C.
CLI summary
The built-in help is the source of truth: dotlink --help, dotlink profile --help, and dotlink oauth --help.
SETUP & PROFILES
-S, --setup interactive setup/editor for the selected profile
-p, --profile <NAME> run/setup with config.<NAME>.jsonc
dotlink profile list
dotlink profile show <NAME>
dotlink profile create <NAME>
dotlink profile edit <NAME>
dotlink profile delete <NAME>
dotlink profile allow <NAME> <read|write|rw> <PATH>
dotlink profile remove-allow <NAME> <read|write|rw> <PATH>
dotlink profile deny <NAME> <read|write|rw> <PATH>
dotlink profile remove-deny <NAME> <read|write|rw> <PATH>
dotlink profile enable <NAME> <SETTING>
dotlink profile disable <NAME> <SETTING>
Persisted SETTING values:
openai, stdio, http, http-ephemeral-url, ngrok, ngrok-ephemeral-url,
oauth, default-allow, shell, network
OAUTH MANAGEMENT
dotlink oauth status [-p <NAME>]
dotlink oauth clients [-p <NAME>]
dotlink oauth revoke [-p <NAME>] <CLIENT_ID>
dotlink oauth revoke-all [-p <NAME>]
TRANSPORTS
--stdio add stdio MCP for this run
--no-stdio suppress profile stdio for this run
--http add HTTP MCP for this run
--no-http suppress profile HTTP + ngrok for this run
--http-bind <ADDR> override HTTP listen address
REMOTE HTTP & OAUTH
--ngrok publish effective HTTP through ngrok
--no-ngrok suppress profile ngrok for this run
--ngrok-domain <DOMAIN> use a stable/reserved ngrok hostname
--no-ngrok-domain ignore persisted ngrok domain for this run
--oauth protect local/reverse-proxied HTTP with OAuth
--no-oauth disable local HTTP OAuth for this run
--public-url <HTTPS-ORIGIN> canonical OAuth origin behind a reverse proxy
--allow-public-no-auth deliberately expose public HTTP/ngrok without OAuth
--ephemeral-url use ephemeral local HTTP + ngrok MCP paths
--http-ephemeral-url[=<BOOL>] override local HTTP path behavior
--ngrok-ephemeral-url[=<BOOL>] override ngrok path behavior
FILESYSTEM ACCESS
--allow-read[=<DIR>] add read; bare means launch directory
--allow-write[=<DIR>] bare: rw launch directory; with DIR: write-only
--allow-rw[=<DIR>] add rw; bare means launch directory
--no-default-allow remove implicit launch-directory read for this run
--deny-read[=<DIR>] deny read; bare means launch directory
--deny-write[=<DIR>] deny write; bare means launch directory
--deny-rw[=<DIR>] deny read+write; bare means launch directory
--deny <PATH> legacy synonym for --deny-rw=<PATH>
SHELL & NETWORK
--allow-shell enable Bash (Unix) / PowerShell (Windows)
--deny-shell disable shell; deny always wins
--allow-network network inside the Linux shell sandbox
--deny-network deny shell network; deny always wins
--allow-rw=/ filesystem rw / while keeping Linux sandboxing
--unrestricted full-host rw / + shell + network + no sandbox
--allow-all --no-sandbox legacy equivalent of --unrestricted
SHELL INTEGRATIONS (Linux Bubblewrap only; separately opted in)
--allow-nix-daemon share only the Nix daemon Unix socket
--allow-nix-config mount user's nix.conf read-only
--allow-ssh-agent share SSH agent socket; never private key files
--allow-git-config mount ~/.gitconfig and XDG Git config read-only
HARDWARE (Linux Bubblewrap; separate opt-in device access)
--allow-kvm pass /dev/kvm for accelerated VMs
--allow-gpu=amd pass AMD GPU render/KFD nodes and driver runtime
--allow-gpu=nvidia pass NVIDIA CUDA/render nodes and driver runtime
--allow-gpu may be repeated for both vendors
DEVELOPER CACHES (discovered paths; bare flag = ro, =rw enables writes)
--allow-cache-cargo-registry[=ro|rw] --allow-cache-cargo-git[=ro|rw]
--allow-cache-npm[=ro|rw] --allow-cache-pnpm[=ro|rw]
--allow-cache-yarn[=ro|rw] --allow-cache-pip[=ro|rw]
--allow-cache-uv[=ro|rw] --allow-cache-go-mod[=ro|rw]
--allow-cache-go-build[=ro|rw] --allow-cache-maven[=ro|rw]
--allow-cache-gradle[=ro|rw] --allow-cache-sccache[=ro|rw]
--allow-cache-ccache[=ro|rw]
OUTPUT & DIAGNOSTICS
--list-tools show tools exposed by the effective policy
--print-id print configured tunnel ID (no Runtime key needed)
-s, --serialize execute MCP tools one at a time (opt-in)
-q, --quiet suppress TOOL activity
-v, --verbose -v TOOL; -vv TOOL + REQ
--color <auto|always|never> control colors in help and human output
dotlink MCP questions
Is dotlink secure for local file access?
Yes, security is local and opt-in; the launch directory is read-only by default, and specific grants are required for write, shell, or network access.
Can I use dotlink with Claude.ai?
Yes, you can connect Claude.ai by publishing a Streamable HTTP server through ngrok and protecting the endpoint with OAuth.
Does dotlink require a public inbound port?
No, it uses an outbound OpenAI Secure MCP Tunnel directly from your machine to OpenAI, meaning no public inbound port is needed.