unlocalhost MCP server
✓ VerifiedDeploys localhost applications to private, authenticated URLs with built-in guest list access control via an AI coding agent.
Also known as info-arnav/unlocalhost, @unlocalhost/unlocalhost
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.1
- Last commit
- Jul 26, 2026
- License
- MIT
What is unlocalhost MCP?
unlocalhost deploys localhost applications to private, authenticated URLs with built-in guest list access control via an AI coding agent.
Summary generated from the project's README
About unlocalhost MCP server
unlocalhost allows developers to transform local applications into private, authenticated web links through an AI coding agent. By adding this MCP server to a client like Claude, you can deploy code by simply telling the agent who should have access. The system handles the entire hosting process, including domain management, certificates, and a built-in login system, so you do not have to write any authentication code yourself.
To use the service, you sign in once using GitHub. When a deployment is triggered, the agent uses your own git credentials to push code to a private repository. The platform then performs a read-only clone and scans for committed secrets to ensure security before building and running the application. Access is restricted to a specific guest list, where visitors must sign in via Google or GitHub to verify their email against your allowed users.
This tool is different from standard tunnels or hosting platforms because it is private by default and survives even after you close your laptop. It can also be self-hosted using Docker Compose if you have a domain with wildcard DNS and the necessary OAuth credentials.
What you can do with it
- 1Deploy a private applicationAsk your AI agent to host your current project and grant access to a specific person.
- 2Securely share work with teammatesProvide a live URL to a colleague that requires them to sign in with their email to view.
- 3Prevent accidental secret leaksUse the automated scanning feature to ensure no API keys are deployed to the web.
Written from the project's README. Every use case is checked against a quote from it.
How to install unlocalhost MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall unlocalhost MCP in Claude Code
$ claude mcp add --env 'UNLOCALHOST_TOKEN=<YOUR_UNLOCALHOST_TOKEN>' unlocalhost -- npx -y @unlocalhost/unlocalhostInstall unlocalhost MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"unlocalhost": {
"command": "npx",
"args": [
"-y",
"@unlocalhost/unlocalhost"
],
"env": {
"UNLOCALHOST_TOKEN": "<YOUR_UNLOCALHOST_TOKEN>"
}
}
}
}Install unlocalhost MCP in VS Code
.vscode/mcp.json
{
"servers": {
"unlocalhost": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@unlocalhost/unlocalhost"
],
"env": {
"UNLOCALHOST_TOKEN": "<YOUR_UNLOCALHOST_TOKEN>"
}
}
}
}Install unlocalhost MCP in VS Code CLI
$ code --add-mcp '{"name":"unlocalhost","type":"stdio","command":"npx","args":["-y","@unlocalhost/unlocalhost"],"env":{"UNLOCALHOST_TOKEN":"<YOUR_UNLOCALHOST_TOKEN>"}}'Install unlocalhost MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"unlocalhost": {
"command": "npx",
"args": [
"-y",
"@unlocalhost/unlocalhost"
],
"env": {
"UNLOCALHOST_TOKEN": "<YOUR_UNLOCALHOST_TOKEN>"
}
}
}
}Install unlocalhost MCP in Codex
$ codex mcp add unlocalhost --env 'UNLOCALHOST_TOKEN=<YOUR_UNLOCALHOST_TOKEN>' -- npx -y @unlocalhost/unlocalhostInstall unlocalhost MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.unlocalhost] command = "npx" args = ["-y", "@unlocalhost/unlocalhost"] [mcp_servers.unlocalhost.env] UNLOCALHOST_TOKEN = "<YOUR_UNLOCALHOST_TOKEN>"
Install unlocalhost MCP in Gemini CLI
$ gemini mcp add -s user -e 'UNLOCALHOST_TOKEN=<YOUR_UNLOCALHOST_TOKEN>' unlocalhost npx -- -y @unlocalhost/unlocalhostInstall unlocalhost MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"unlocalhost": {
"command": "npx",
"args": [
"-y",
"@unlocalhost/unlocalhost"
],
"env": {
"UNLOCALHOST_TOKEN": "<YOUR_UNLOCALHOST_TOKEN>"
}
}
}
}Configuration
UNLOCALHOST_TOKENSecretAPI token. Normally written by the unlocalhost_login tool after you approve the device in a browser, so you should not need to set this by hand.
UNLOCALHOST_URLBase URL of the unlocalhost instance to talk to. Defaults to the hosted instance. Set this to point the tools at your own self hosted deployment.
| Name | Description | |
|---|---|---|
| UNLOCALHOST_TOKEN | API token. Normally written by the unlocalhost_login tool after you approve the device in a browser, so you should not need to set this by hand. | Secret |
| UNLOCALHOST_URL | Base URL of the unlocalhost instance to talk to. Defaults to the hosted instance. Set this to point the tools at your own self hosted deployment. |
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableinfo-arnav/unlocalhost is public and reachablegithub.com/info-arnav/unlocalhost ↗Pass
- Package names this repository as its source@unlocalhost/unlocalhost names info-arnav/unlocalhost as sourcenpmjs.com/package/@unlocalhost/unlocalhost ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-07-26github.com/info-arnav/unlocalhost ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @unlocalhost/unlocalhostPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- 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 GitHubunlocalhost
Turn localhost into a link only the people you name can open.
Sign in is built in, so you write no auth code and touch no servers.
Website · Docs · MIT licensed · Self hostable
The problem
Your coding agent can write the whole application. It cannot host it, because hosting needs a server, a domain, a certificate, and a login system. So people reach for whatever is fastest, and that is where things go wrong: a public URL with no sign in, an API key committed by accident, or auth bolted on at the end by someone who has never written auth.
unlocalhost closes that gap. You say one sentence to the agent you already have open, and you get back a real URL with a guest list in front of it.
you deploy this and let sarah@gmail.com in
agent pushed your code to a private repo
agent building
agent live at sarahs-todo.unlocalhost.tech
agent sarah@gmail.com can sign in and open it
How it works
- You add unlocalhost to your coding agent as an MCP server and sign in once with GitHub.
- You tell the agent to deploy, and name who is allowed in.
- Your agent pushes the code using your own git credentials. unlocalhost never holds write access to anything.
- We clone read only, scan for committed secrets and refuse to continue if we find any, then build and run it.
- Visitors sign in with GitHub or Google. Their verified email is checked against the guest list before the request ever reaches your app.
What makes it different
| Tunnel (ngrok) | Platform (Vercel) | unlocalhost | |
|---|---|---|---|
| Survives closing laptop | No | Yes | Yes |
| Private by default | No | No | Yes |
| Auth you have to write | All of it | All of it | None |
| Runs on your own server | No | No | Yes |
Quick start
claude mcp add unlocalhost -- npx -y @unlocalhost/unlocalhost
Or in any MCP client config:
{
"mcpServers": {
"unlocalhost": {
"command": "npx",
"args": ["-y", "@unlocalhost/unlocalhost"]
}
}
}
Then ask your agent to sign in to unlocalhost, and deploy.
Self hosting
The hosted service runs this exact code. Nothing is held back, there is no phone home, and no license check.
git clone https://github.com/info-arnav/unlocalhost.git
cd unlocalhost/deploy
cp .env.example .env # fill it in
docker compose --env-file .env run --rm migrate
docker compose --env-file .env up -d
You need a domain with wildcard DNS, a DNS provider API token for wildcard TLS,
a GitHub App, and a Google OAuth client. The full walkthrough is in
docs/server-setup.md.
Architecture
internet :443 → Caddy → auth-gate /verify → activator → Dokku → your app
| Package | Job |
|---|---|
web |
Landing page, sign in screens, docs |
server/gateway |
Public API ingress, CORS, rate limiting, request ids |
server/services/auth-gate |
OAuth, sessions, and the allowlist check on every request |
server/services/control-plane |
Apps, sharing, GitHub App, deploy pipeline |
server/services/activator |
Wakes sleeping apps, puts idle ones back to sleep |
server/services/mcp-server |
The unlocalhost npm package your agent talks to |
server/shared |
Database, logging, crypto, errors, sessions |
Borrowed rather than built: Dokku and Nixpacks turn a repository into a running container, Caddy handles wildcard TLS. The novel part is small on purpose.
Security
- Apps are private until you name someone. Removing them revokes access at once.
- Every deploy is scanned for committed secrets and refused if any are found.
- Sign in is enforced at the edge, before a request reaches your app.
- Environment variables are encrypted at rest with AES 256 GCM.
- We hold read only access, and only to repositories you pick.
Found a vulnerability? Please follow SECURITY.md rather than
opening a public issue.
Contributing
Read CONTRIBUTING.md first. In short: every backend module
follows routes → controller → service → repository, code carries no comments,
and there are no test files. Verification is done by running things.
Licence
MIT. See LICENSE.
unlocalhost MCP questions
How do I add unlocalhost MCP to Claude Code?
Run claude mcp add --env 'UNLOCALHOST_TOKEN=<YOUR_UNLOCALHOST_TOKEN>' unlocalhost -- npx -y @unlocalhost/unlocalhost in your terminal. Add --scope user to make it available in every project.
How do I add unlocalhost MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does the agent need to provide my git credentials?
Yes, your agent uses your own git credentials to push code, ensuring unlocalhost never holds write access.
Can I run unlocalhost on my own infrastructure?
Yes, the service is self-hostable using Docker Compose and requires a domain with wildcard DNS.
How is access controlled for visitors?
Visitors must sign in with GitHub or Google, and their verified email is checked against a guest list before reaching your app.