Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TunnelGPT MCP Core Show me the contents of hello.txt in the project folder"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
One local project folder, file tools and a bounded MCP socket. That is the open-source core.
MIT license · TunnelGPT · Built by Carlos Rodera
If you want to wire your own connection instead of using the TunnelGPT application, this package is the starting point: give an MCP client access to one project directory over a private Unix socket, with explicit limits on what it can read and change.
This is not the desktop app, not a multi-project router, and not a ChatGPT tunnel. A local socket does not establish a remote connection by itself.
Component | What it does |
Path authorization | Resolves paths inside the configured project folder, applies deny rules, and supports rejecting symlinks and hard links. |
File tools | Reads and searches text, walks project files, and applies bounded text file operations. |
Confirmed writes | Previews changes and binds confirmation tokens to the proposed operation. Read-only mode refuses writes. |
MCP protocol | Message framing, discovery, header validation and protocol adapters. |
Local transport | HTTP over a Unix socket, with limits on request size, concurrent work, queue length and timeouts. |
Related MCP server: srcbridge
The TunnelGPT application stays private. It is not published here:
Desktop UI, accounts, licenses and guided setup
Remote tunnel and ChatGPT connector
One route per project, and switching between several local projects
Extra local MCP servers and product-only file transfer
Authentication, user approval, process isolation and remote tunnel setup belong to the host you build, or to the TunnelGPT application if you use that instead.
Requires Node.js 22.12 or later. The Unix-socket example is intended for macOS and Linux.
git clone https://github.com/carlosrodera/tunnelgpt-mcp-core.git
cd tunnelgpt-mcp-core
npm ci --ignore-scripts
npm run build
mkdir -p /tmp/tunnelgpt-core-demo
printf 'Hello from a local project.\n' > /tmp/tunnelgpt-core-demo/hello.txt
node examples/project.mjs /tmp/tunnelgpt-core-demo /tmp/tunnelgpt-core-demo/mcp.sockThe example exposes read_project_file for that one folder. In a second terminal:
curl --unix-socket /tmp/tunnelgpt-core-demo/mcp.sock \
http://localhost/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-11-25' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_project_file","arguments":{"path":"hello.txt"}}}'Stop the server with Ctrl+C. Restart it with --edit to also expose create_project_file. Its first call returns a proposal. Applying it requires the same arguments, its confirmation token and confirmed: true. The host must obtain the user's approval before confirming a write.
See the complete example for configuration and tool registration, and the tests for executable read, write and transport cases.
Install @tunnelgpt/mcp-core 0.4.0 from an immutable commit on main after this release lands:
npm install --save-exact --ignore-scripts \
https://github.com/carlosrodera/tunnelgpt-mcp-core/archive/v0.4.0.tar.gzThe package includes compiled JavaScript and TypeScript declarations. It is currently distributed through GitHub; the command above does not depend on an npm registry publication.
Exports include PathAuthorizer, SafeReader, AtomicWriter, SignedTokenCodec, UnixHttpMcpServer and createCoreMcpHandler. The entry point lists the public exports. Keep the resolved integrity in your lockfile when updating.
The authorizer can accept more than one folder because that is how a host names roots. The gift, the example and the intended DIY setup are still one project, one socket. Routing several projects, each with its own remote connector, is product work.
This repository is licensed under MIT. You can study, modify, use and redistribute this code under that license.
TunnelGPT is the commercial application built on top of this core. The MIT scope is the code in this repository. It does not promise that product features will be published here.
TunnelGPT is independent software and is not affiliated with, sponsored by or endorsed by OpenAI.
Issues and pull requests are welcome. Useful contributions include reproducible bugs, clearer examples, path-boundary tests, protocol interoperability and improvements to the public API.
Before opening a pull request, run:
npm ci --ignore-scripts
npm run check
node scripts/verify-package.mjs
npm audit --audit-level=lowInclude a regression test for behavior changes and rebuild dist when changing TypeScript. CI checks types, functional tests, reproducible build output, dependency licenses and CodeQL. Keep proposals inside this core. Do not add desktop, billing, multi-project distribution, remote tunnels or product-only transfer.
Created and maintained by Carlos Rodera.
MIT. Original copyright notices are retained. Dependency notices are listed in THIRD_PARTY_NOTICES.
This server cannot be deployed
Project management MCP for AI agents with safe task reads and writes.
Read and write shared BitsWeave context, projects, tasks, and work sessions through MCP.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Browse and manage files in your Moxt AI workspace from any MCP client.
