TUUI: a desktop MCP client that keeps your API keys local

What TUUI solves, and who it is actually for

The Model Context Protocol defines how an LLM host talks to tool servers, but the host itself has to exist. TUUI is that host, shipped as a desktop application rather than a library. The README describes it as "a desktop MCP client designed as a tool unitary utility integration", and the package.json name field expands to "Tool Unitary User Interface".

The audience is narrow on purpose. Someone who wants to see what an MCP server exposes should not have to write a client first. TUUI gives that person a window, a config file and a chat box. The README's own tagline is "Zero accounts, Full control, Open source, Download and Run", which is a claim about the setup path: no sign-up, no hosted relay, no vendor account between you and the model.

The second audience is people who already pay for several model providers and want one interface for all of them. The README calls this "cross-vendor LLM API orchestration", and the configuration format backs it up. You describe each backend as a JSON object with a url, a path and a model, and TUUI treats them as interchangeable chat endpoints. That is the whole product thesis: MCP on the tool side, OpenAI-compatible HTTP on the model side, and a desktop shell around both.

How the MCP host, the config files and localStorage fit together

The repository is an Electron application built with Vue 3, Vuetify and a Pinia store, written in TypeScript. That stack matters because it explains where behaviour lives. The main process owns the filesystem and the configuration assets; the renderer owns the chat UI and the Pinia state; the preload layer exposes typed bridges, and the type definitions for the LLM config live in src/preload/llm.d.ts.

The default configuration ships as JSON inside the app. The README lists four files: src/main/assets/config/llm.json for LLM endpoints, mcp.json for MCP servers, startup.json for the news shown on the startup screen, and popup.json for startup prompts. In a built release those paths move under resources/assets/config/. This is a deliberate design choice, and it has a consequence worth stating plainly: the app is configurable by editing files that ship inside the bundle, so upgrading the app can overwrite whatever you changed there.

Changes you make through the UI do not go back into those files. The README says that once you modify or import configurations, they are stored in your localStorage by default. So there are two layers, a shipped default and a per-user override, and the shipped default is the one an upgrade replaces. The README also notes you can clear all configurations from the Tray Menu, which is the escape hatch when a bad import leaves the app in a state you cannot navigate out of.

On the MCP side, the feature table is the most useful page in the README. Tools, Prompts and Resources are marked supported on the server side. Sampling and Elicitation are marked supported on the client side. Discovery is supported against the MCP registry, and MCPB bundles, formerly Desktop Extensions or .dxt, are supported as an extension format. Roots is the one row marked not implemented, with the README's own explanation that it is "generally only used for the Vibe Coding IDE and can typically be configured through server environment variables". That is a defensible position, but it is still a gap, and anyone building a server that depends on root negotiation should treat TUUI as the wrong client.

Installing TUUI and adding your first MCP server

There are two paths, and the README separates them by role. If you just want the application, the README points to the releases page at github.com/AI-QL/tuui/releases/latest, with builds listed for Windows, Linux and macOS. Nothing to compile, no Node.js requirement for the app itself.

If you want to build from source, the package.json scripts are the entry point. The dev script runs Vite, and package.json sets VITE_DEV_SERVER_URL to http://localhost:5173 in its debug environment block. The build pipeline runs a format pass, then vue-tsc --noEmit, then vite build, before electron-builder packages the result. The README's developer note is blunt about this: the project was largely generated by AI, so it "employs strict syntax checks and naming conventions", and contributors are told to run the configured linting tools. Expect the type check to be a real gate, not a formality.

Before any MCP feature works, the README lists preconditions. You need an LLM backend that supports tool or function calling. For NPX or Node-based MCP servers you need Node.js. For UV or UVX servers you need Python and the uv library. For Docker-based servers you need Docker. On macOS and Linux the README warns that you should modify the default MCP configuration, adjusting CLI paths or permissions, and points to an MCP Server Issue section of the docs.

Adding a model backend is a JSON edit. The README gives this single-chatbot template using Qwen:

{
  "name": "Qwen",
  "apiKey": "",
  "url": "https://dashscope.aliyuncs.com/compatible-mode",
  "path": "/v1/chat/completions",
  "model": "qwen-turbo",
  "modelList": ["qwen-turbo", "qwen-plus", "qwen-max"],
  "maxTokensValue": "",
  "mcp": true
}

The apiKey field is left empty in the template and you fill it in locally. The mcp flag is what enables tool calling for that backend, so a backend configured with mcp set to false will chat but will not use MCP servers. The same file accepts an array when you want several providers at once, and the README's second example mixes an OpenRouter-style entry with a DeepInfra entry that uses the path /v1/openai/chat/completions rather than /v1/chat/completions. That path field is not decoration: it is how TUUI accommodates providers that expose an OpenAI-compatible surface at a non-standard route.

MCP servers themselves go in mcp.json, and the README defers to the modelcontextprotocol/servers repository for the configuration syntax rather than restating it. That is the honest place to look, but it also means the README alone will not tell you the exact shape of a server entry. Once the app is running, an MCP server you have configured should appear in the interface with its exposed tools, and a prompt that needs a tool should trigger a call through the backend you marked with mcp set to true.

Where TUUI gets in the way

The configuration model is the first friction point. Because user changes land in localStorage and shipped defaults live inside the app bundle, there is no documented config file you can commit, review, or hand to a colleague. The README does not describe an export that writes your working setup back to a portable file, only an import and a Tray Menu option to clear everything. If your team wants a shared, version-controlled MCP server list, TUUI does not offer an obvious route to it.

The second issue is the tool-calling dependency. MCP is only useful when the model can call functions, and the README states this as a precondition rather than handling it. Point TUUI at a backend that lacks function calling and the MCP servers you configured become inert. There is no fallback described.

Third, the Roots gap. A server that expects the client to declare filesystem roots will not get them. The README suggests configuring that through server environment variables instead, which works when the server supports it and does nothing when it does not.

Fourth, platform friction. The README explicitly tells macOS and Linux users to adjust CLI paths or permissions before MCP servers will run. That is not a bug report, it is a documented setup step, but it means the first-run experience on those platforms is not "download and run" in the literal sense the tagline suggests. Windows users are not given the same warning.

Finally, the project describes itself as an experiment in building a complete project with AI, with many components "directly converted or generated from the prototype project through AI". That is stated openly, and it is a reasonable thing to weigh when you decide how much of your workflow to put behind this client. The repository was last pushed on 2026-05-14, and the latest release, v1.5.1, is dated the same day.

TUUI against a terminal MCP client or a coding IDE

The closest alternative in spirit is a command-line MCP host, the kind of tool people reach for when they want to script a server and inspect its output. The difference is architectural. A terminal client runs in your shell, reads config from files you already manage with dotfiles, and composes with pipes and scripts. TUUI is an Electron app with a GUI, a Pinia store and localStorage. You get discovery, a chat surface and a tray menu; you give up scriptability and the ability to diff your configuration in git.

The other alternative is an IDE that has adopted MCP natively. Those tools bundle the client with an editor and a project context, which is exactly the scenario the README cites when it explains why Roots is unimplemented: root negotiation matters most for coding IDEs. If your MCP work is about letting a model read and edit a codebase, an IDE-integrated client is the more direct fit, and TUUI's own feature table concedes the point. TUUI's advantage in that comparison is neutrality: it is not tied to one editor, one model vendor or one account, and the README's multi-entry LLM config shows that switching providers is a JSON edit rather than a reinstall.

Editorial conclusion

Adopt TUUI if you want a local, account-free way to try MCP servers and switch between OpenAI-compatible endpoints. Skip it if you need a headless host, a shared team configuration, or MCP Roots support, which the README marks as not implemented. Before committing, verify two things: that your chosen LLM backend actually supports tool calling, and that your local MCP server launches under the CLI paths TUUI uses on macOS or Linux.

Frequently asked questions

Official sources

1. AI-QL/tuui on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases