Qodalis CLI MCP server
Commit Nov 5, 2026Enables Claude Code to build Qodalis CLI plugins and interact with running Qodalis CLI servers via a resilient proxy.
Also known as qodalis-solutions/mcp-cli
- Stars
- 0
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 5, 2026
- License
- MIT
What is Qodalis CLI MCP?
Qodalis CLI enables Claude Code to build Qodalis CLI plugins and interact with running Qodalis CLI servers via a resilient proxy. It exposes 5 tools, such as qcli_docs_search, qcli_docs_read, qcli_api.
Summary generated from the project's README
About Qodalis CLI MCP server
Building Qodalis CLI plugins and managing running server instances is what developers achieve using this MCP server within Claude Code. It functions as a bridge that provides the assistant with access to documentation, API declarations, and scaffolding tools for plugin creation. When configured in server mode, it acts as a resilient proxy that passes through the tools, files, and data explorer of a live Qodalis CLI server directly to the AI client.
Users can run this as a local stdio server in developer mode for plugin creation without needing a live backend. For remote interaction, providing a QCLI_URL along with a QCLI_TOKEN or user credentials allows the assistant to execute commands with the permissions of the configured account. The server includes safety features like a read-only mode, tool allow and deny lists, and a self-healing connection that handles network drops and automatic session renewal.
What you can do with it
- 1Scaffold new CLI pluginsAsk the assistant to generate the initial file structure and boilerplate for a new Qodalis plugin.
- 2Research API specificationsRetrieve exact TypeScript declarations and JSDoc for core library interfaces to ensure code accuracy.
- 3Manage remote server toolsDirect the AI to interact with a running Qodalis server using its existing commands and data explorer.
- 4Search technical documentationQuery the plugin guide to find specific topics or implementation details for development.
Written from the project's README. Every use case is checked against a quote from it.
Qodalis CLI MCP tools 5
Detected from the READMEqcli_docs_searchqcli_docs_readqcli_apiqcli_scaffold_pluginserver_info
Configuration
QCLI_EXCLUDEQCLI_PASSWORDQCLI_READ_ONLYQCLI_TOKENQCLI_TOOLSQCLI_URLQCLI_USER
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 reachableqodalis-solutions/mcp-cli is public and reachablegithub.com/qodalis-solutions/mcp-cli ↗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-05github.com/qodalis-solutions/mcp-cli ↗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 model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@qodalis/mcp-cli
A Model Context Protocol server that helps Claude Code build Qodalis CLI plugins (docs search, exact API declarations, scaffolding) and gives it the commands, files, data explorer, jobs and plugin tools of a running Qodalis CLI server through a resilient proxy.
mcp-cli runs on your machine as a stdio MCP server in one of two modes:
- Developer mode (no
QCLI_URL): the plugin-development tools only. No server needed. - Server mode (
QCLI_URLset): the same tools plus a proxy to the server's MCP endpoint (<server>/api/qcli/mcp): Claude Code sees exactly the server's tools, with the permissions of the account you configure. It handles sign-in, reconnects after network drops and lets you narrow what the assistant may use.
Where it fits
| Repository | Role |
|---|---|
| web-cli | The browser terminal (Angular, React, Vue) and its plugins, including token create for API tokens |
| cli-server-node, cli-server-dotnet, cli-server-python | The servers that host the MCP endpoint |
| cli-server-dashboard | Admin dashboard served by the servers |
| pwa-cli | The CLI as a PWA and Android app |
| mcp-cli | This repository: the bridge from Claude Code to a server |
Highlights
- Plugin development built in. Search the plugin guide, read the exact
TypeScript declarations of
@qodalis/cli-coreand scaffold a plugin, with prompts that walk the assistant through a web plugin or a server command. - No tool-specific code. Tools come from the server's
tools/listand are passed through unchanged (names, schemas, annotations); calls are forwarded. New commands on the server show up without updating the proxy. - Token or password. Use an API token (
QCLI_TOKEN), or sign in withQCLI_USER/QCLI_PASSWORD; an expired session is renewed automatically on the next call. - Read-only mode (
QCLI_READ_ONLY=true) exposes only the tools the server marks read-only, and refuses calls to anything else. - Client-side allow and deny lists (
QCLI_TOOLS,QCLI_EXCLUDE, trailing*allowed) on top of the server's own permissions. - Self-healing connection. It connects on first use, never caches a failed connect, retries once when the connection drops, and fails fast (8 s) when the server is unreachable, with a message that says what to check.
- Clear errors: a rejected token, MCP not enabled on the server, a missing permission or an unreachable host each come back as one actionable sentence.
Quick start
For plugin development, nothing else is needed:
claude mcp add qcli -- npx -y @qodalis/mcp-cli
Then ask, for example, "Create a Qodalis CLI plugin that converts temperatures" or run the
/mcp__qcli__create-web-plugin prompt. See Plugin development.
To also reach a running server, add QCLI_URL and credentials as described below.
npx -y @qodalis/mcp-cli --help
The server must have MCP enabled (default ports: .NET 8046, Node 8047, Python 8048):
| Server | Enable MCP |
|---|---|
| Node | createCliServer({ mcp: true }) |
| Python | CliServerOptions(mcp=True) |
| .NET | builder.Services.AddCli(cli => cli.AddMcp()) |
Each also takes options (tool allow/deny lists, a static token, instructions); see MCP endpoint.
Claude Code
claude mcp add qcli -- npx -y @qodalis/mcp-cli
then set the environment in ~/.claude.json:
{
"mcpServers": {
"qcli": {
"command": "npx",
"args": ["-y", "@qodalis/mcp-cli"],
"env": {
"QCLI_URL": "http://localhost:8047",
"QCLI_TOKEN": "qcli_pat_..."
}
}
}
}
or sign in with a user name and password instead of a token:
"env": {
"QCLI_URL": "http://localhost:8047",
"QCLI_USER": "ops",
"QCLI_PASSWORD": "********"
}
The same in one command, with -e flags:
claude mcp add qcli -e QCLI_URL=http://localhost:8047 -e QCLI_TOKEN=qcli_pat_... -- npx -y @qodalis/mcp-cli
Add --scope user to make it available in every project. With
--scope project the entry goes into the project's .mcp.json, which is
usually committed: keep the secret out of it with
"QCLI_TOKEN": "${QCLI_TOKEN}" and set the variable in your shell. A .env
file works too:
{ "command": "npx", "args": ["-y", "@qodalis/mcp-cli", "--env-file", "/path/to/.env"] }
Pin a version in shared configs (@qodalis/mcp-cli@0.2.0) so an upgrade is a
deliberate change.
Getting a token
In the web CLI connected to the server (users plugin), signed in as the account the assistant should act as:
token create claude --expires=90
# token create claude --permissions=commands:execute,files:read (narrower scope)
The token (qcli_pat_…) is shown once. Without the web CLI, sign in and create
one with curl:
SESSION=$(curl -s http://localhost:8047/api/v1/qcli/sessions \
-H 'Content-Type: application/json' -d '{"username":"ops","password":"..."}' | jq -r .token)
curl -s http://localhost:8047/api/v1/qcli/tokens -H "Authorization: Bearer $SESSION" \
-H 'Content-Type: application/json' -d '{"name":"claude","expiresInDays":90}' | jq -r .token
curl -s -X DELETE http://localhost:8047/api/v1/qcli/sessions/current -H "Authorization: Bearer $SESSION"
A server without the users plugin protects its endpoint with a static token
(its mcp.token option): put that value in QCLI_TOKEN. If it sets none, the
endpoint is open and no auth variable is needed.
Plugin development
These tools are served locally and work without a server (developer mode) or next to
a server's tools. Turn them off with QCLI_DEV_TOOLS=false.
claude mcp add qcli -- npx -y @qodalis/mcp-cli # developer mode
claude mcp add qcli --scope user -- npx -y @qodalis/mcp-cli # in every project
Tools
| Tool | Arguments | What it does |
|---|---|---|
qcli_docs_search |
query, limit? (default 5, max 20) |
Ranked topics of the plugin guide as Section › Topic, with their summary and an excerpt. |
qcli_docs_read |
topic |
A topic in full (heading match, case-insensitive; Section › Topic when a heading is in several sections), or a whole section (Web plugins). Lists the topics when nothing matches. |
qcli_api |
symbol, package? (default @qodalis/cli-core) |
The TypeScript declaration of an interface, type, class, function, enum or constant, with its JSDoc and the related declarations to look up next. package takes any @qodalis/* package (cli is short for @qodalis/cli). |
qcli_scaffold_plugin |
name, description?, processorName?, directory? |
Runs npx -y @qodalis/create-cli-plugin@latest and returns the created files and next steps. Inside a web-cli checkout it creates packages/plugins/<name>; elsewhere a standalone qodalis-cli-<name> project. |
Where the data comes from:
- Docs:
https://cli.qodalis.com/llms-full.txt(QCLI_DOCS_URL), cached for an hour. When it cannot be fetched, the last download is reused, else the snapshot bundled in the package (docs/llms-full.txt), so the tools work offline. - API declarations: the project's
node_modules(the MCP server's working directory and its parents) when the package is installed there, so the answer matches the version you build against. Otherwise thelatestversion on npm, downloaded from jsDelivr (unpkg as fallback) and cached in memory and in<tmp>/qodalis-mcp-cli; offline, the newest cached version is used. - Scaffolding: validates the name (lowercase letters, digits and hyphens, no
cli-prefix), refuses an existing target directory, runs without a TTY and stops after 5 minutes. The standalone project installs its dependencies.
Prompts
| Prompt | Arguments | Walks the assistant through |
|---|---|---|
create-web-plugin |
name, description |
Reading the guide, looking up the contracts with qcli_api, scaffolding, implementing the processor and module, tests, registering it. |
create-server-command |
language (node, dotnet, python), command |
Adding a command processor to a Node, .NET or Python server, registering it and testing it. |
In Claude Code they appear as /mcp__qcli__create-web-plugin and
/mcp__qcli__create-server-command. The docs topics are also MCP resources
(qcli-docs://<section>/<topic>), which Claude Code can attach with @.
Example requests
- "Search the Qodalis plugin docs for reading user input." →
qcli_docs_search - "Show me ICliExecutionContext." →
qcli_api { "symbol": "ICliExecutionContext" } - "Which options does CliEngine take?" →
qcli_api { "symbol": "CliEngine", "package": "cli" } - "Scaffold a plugin called json-tools." →
qcli_scaffold_plugin { "name": "json-tools" }
Filters and read-only mode
The dev tools are tools like any other: QCLI_TOOLS and QCLI_EXCLUDE apply to
them (QCLI_EXCLUDE=qcli_scaffold_plugin, or QCLI_TOOLS=qcli_* for the dev
tools alone), and QCLI_READ_ONLY=true hides and refuses qcli_scaffold_plugin
(the docs and API tools are read-only). A server tool with the same name as a dev
tool is hidden. When the server is unreachable, tools/list still returns the
dev tools.
Configuration
Every setting is an environment variable. QODALIS_CLI_* names are accepted as
aliases for every key.
| Variable | Default | Description |
|---|---|---|
QCLI_URL |
none | Server base URL, e.g. https://cli.example.com (a pasted …/api/qcli/mcp URL is accepted). Without it: developer mode. |
QCLI_TOKEN |
none | API token (token create in the web CLI) or the server's static mcp.token. |
QCLI_USER |
none | Sign in with this user name instead of a token (needs QCLI_PASSWORD). |
QCLI_PASSWORD |
none | Password for QCLI_USER. Never logged. |
QCLI_READ_ONLY |
false |
Expose and allow only tools annotated readOnlyHint: true. See read-only mode. |
QCLI_TOOLS |
all | Comma-separated allow-list of tool names; a trailing * matches a prefix (fs_*). |
QCLI_EXCLUDE |
none | Comma-separated deny-list, same syntax, applied after QCLI_TOOLS. |
QCLI_CONNECTION_TIMEOUT |
8000 |
Milliseconds to wait for the TCP/TLS connection before reporting the server unreachable. |
QCLI_REQUEST_TIMEOUT |
60000 |
Milliseconds a single request (tools/list, tools/call) may take. |
QCLI_TRUST_CERT |
false |
Accept a self-signed TLS certificate. |
QCLI_ENV_FILE |
none | Path to a .env file (same as --env-file). Variables already set in the environment win. |
QCLI_DEV_TOOLS |
true |
The qcli_* plugin-development tools, prompts and docs resources. false requires QCLI_URL. |
QCLI_DOCS_URL |
https://cli.qodalis.com/llms-full.txt |
Where the plugin guide is fetched from (falls back to the bundled snapshot). |
Set either QCLI_TOKEN or QCLI_USER + QCLI_PASSWORD, not both.
Tools
The tools are whatever the server exposes to your account. A typical server offers:
| Tools | Available when |
|---|---|
server_info |
always: version, enabled features |
one tool per CLI command (weather, weather_current, ...) |
always |
fs_list, fs_stat, fs_read, fs_write, fs_mkdir, fs_delete |
the server's filesystem API is enabled |
data_sources, data_schema, data_query |
the data explorer is enabled |
jobs_list, jobs_get, jobs_history, jobs_trigger, ... |
the jobs plugin is installed |
| plugin tools | a server plugin contributes them |
Each one is limited by the account's permissions on the server (for example
commands:execute, files:read / files:write, data:query, jobs:manage),
and by the token's scope when it was created with --permissions.
Read-only mode
With QCLI_READ_ONLY=true the proxy lists only the tools the server annotates
readOnlyHint: true (such as server_info, fs_list, fs_read,
data_schema, jobs_list) and refuses calls to any other tool before they
reach the server. Command tools carry no read-only annotation, so they are
hidden in this mode; add the ones you want with a separate, non-read-only entry
and QCLI_TOOLS.
The filter is defence in depth. The real boundary is the account: give the assistant a user (or a token scope) with only the permissions it should have.
Several servers
Add one entry per server (and per access level) with a distinct name:
{
"mcpServers": {
"qcli-dev": {
"command": "npx",
"args": ["-y", "@qodalis/mcp-cli"],
"env": { "QCLI_URL": "http://localhost:8047", "QCLI_TOKEN": "qcli_pat_dev..." }
},
"qcli-prod": {
"command": "npx",
"args": ["-y", "@qodalis/mcp-cli"],
"env": {
"QCLI_URL": "https://cli.example.com",
"QCLI_TOKEN": "qcli_pat_prod...",
"QCLI_READ_ONLY": "true"
}
},
"qcli-prod-jobs": {
"command": "npx",
"args": ["-y", "@qodalis/mcp-cli"],
"env": {
"QCLI_URL": "https://cli.example.com",
"QCLI_TOKEN": "qcli_pat_prod...",
"QCLI_TOOLS": "jobs_*,server_info",
"QCLI_EXCLUDE": "jobs_cancel"
}
}
}
}
Troubleshooting
claude mcp list shows whether each server connects; inside a session /mcp
shows its status and tools and lets you reconnect. The proxy logs to stderr
(claude --debug shows it).
| Message | What to do |
|---|---|
… answered 401 (not authenticated): QCLI_TOKEN is wrong, expired or revoked |
Create a new token (token create claude) and update QCLI_TOKEN. token list in the web CLI shows expiry dates. |
… rejected QCLI_USER / QCLI_PASSWORD |
Check the credentials; the account may be disabled or locked out after failed sign-ins. |
… answered 403 … |
The account lacks commands:execute, or the server rejected the request origin. |
MCP is not enabled on this server (enable the mcp option) |
Turn on the server's mcp option and restart it; check QCLI_URL (base URL, not a page of the web app). |
Cannot reach … Check QCLI_URL / VPN. |
The server is down, the URL or port is wrong, or the VPN is disconnected. Retry the call once it is back: the proxy reconnects by itself. |
… did not answer within 60000 ms |
A slow command; raise QCLI_REQUEST_TIMEOUT. |
| A tool is missing | The account (or token scope) lacks its permission, the feature is not enabled on the server, or QCLI_READ_ONLY / QCLI_TOOLS / QCLI_EXCLUDE hide it. |
Nothing to serve: set QCLI_URL … at startup |
QCLI_DEV_TOOLS=false without QCLI_URL: set the URL (check the variable name; npx -y @qodalis/mcp-cli --help lists every variable). |
Only the qcli_* tools are listed |
No QCLI_URL (developer mode), or the server is unreachable: the log says which. |
How reconnection works
- The proxy connects to the endpoint on the first
tools/listortools/call, not at startup, so Claude Code starts even when the server is down. - A failed connect is not cached: the next call tries again.
- A connection-level error (refused, reset, socket closed, DNS failure) drops
the connection and retries the request once on a fresh one. A connect timeout
is not retried, so an unreachable host fails within
QCLI_CONNECTION_TIMEOUT. - With
QCLI_USER/QCLI_PASSWORD, a 401 signs in again and retries once. - The tool list is cached for 60 s; a call to a tool the proxy does not know yet refreshes it first, so new server commands work without a restart.
Security notes
- Tokens and passwords are read from the environment, sent only to
QCLI_URL, and never written to logs or tool results. - Prefer an API token with a narrow
--permissionsscope and an expiry over a password; revoke it withtoken revoke <id>when it is no longer needed. - Use
https://for anything butlocalhost.QCLI_TRUST_CERT=truedisables certificate verification for this process; use it only for self-signed certificates you control. - Nothing is written to stdout except the MCP protocol stream.
See SECURITY.md for reporting vulnerabilities.
Library use
The pieces are exported for embedding:
import { createProxyServer, loadConfig, RemoteServer } from '@qodalis/mcp-cli';
const config = loadConfig(process.env);
const remote = new RemoteServer(config, { clientInfo: { name: 'my-app', version: '1.0.0' } });
const server = createProxyServer(remote, config); // a low-level MCP Server: connect any transport
With the plugin-development tools (remote may be undefined for developer mode):
import { createProxyServer, DevTools, loadConfig } from '@qodalis/mcp-cli';
const config = loadConfig(process.env);
const server = createProxyServer(undefined, config, { dev: new DevTools(config) });
Qodalis CLI MCP questions
What tools does Qodalis CLI MCP provide?
It exposes 5 tools, including qcli_docs_search, qcli_docs_read, qcli_api, qcli_scaffold_plugin, server_info.
How does the server handle connection drops?
It features a self-healing connection that retries once if the connection drops and provides actionable error messages.