Allows interaction with the Unraid API via GraphQL, enabling AI agents to query and manage Unraid server resources such as shares, VMs, Docker containers, array, and more.
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., "@unraid-code-mode-mcp What's the current array status and list shares?"
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.
This Model Context Protocol server exposes search and execute.
The agent searches the API reference, then runs JavaScript inside a QuickJS WASM sandbox.
API calls go through the host; credentials remain outside the sandbox.
Search the schema. Introspection with a bundled SDL fallback.
Call typed operations. unraid.local.query.* and unraid.local.mutation.*, plus raw GraphQL.
Batch independent reads. Sequential await and Promise.all use the Promise-callback host bridge.
Choose credentials per request. Environment variables for stdio; X-Unraid-* headers for HTTP.
Related MCP server: mcp-graphql-bridge
Install from source and point your MCP client at the built dist/index.js.
Node.js 22.19.0 or newer and npm. CI checks Node 22 and 24.
Unraid 7.2+ with an API key and a reachable GraphQL API.
git clone https://github.com/jmpijll/unraid-code-mode-mcp.git
cd unraid-code-mode-mcp
npm ci
cp .env.example .env
# Edit .env: UNRAID_BASE_URL and UNRAID_API_KEY.
npm run build
npm startThe shell examples use Bash. In PowerShell, use Copy-Item .env.example .env and
set variables with $env:NAME = 'value'.
Configure your MCP client with node /absolute/path/to/unraid-code-mode-mcp/dist/index.js.
Use an absolute path and supply credentials through the client's environment configuration
when its working directory does not contain your .env file.
See the client setup and usage guide.
For hosted use, set MCP_TRANSPORT=http and follow the per-request credential contract.
Docker instructions are in docker-compose.yml.
After discovering the operation with the search tool, use the execute tool:
const info = await unraid.local.query.info({ fields: 'os { distro release kernel }' });
return info;See the usage guide for search recipes, configuration and additional call shapes.
Area | Current boundary |
API coverage | Local GraphQL only; |
Mutations | VM start/stop was historically verified; other mutations need separate validation. |
Workers | Scaffold; full MCP transport is not implemented. |
Sandbox | Resource limits bound each invocation; allowed API calls still act with the supplied account's permissions. |
Earlier maintainer runs cover one Unraid 7.2 box, VM start/stop, cursor-agent and an opencode schema-only run. The opencode live execute run encountered an upstream CSRF failure. Hosted multi-tenancy and other hardware remain unverified. See the setup and verification reference for the detailed historical evidence and remaining work. New verification reports should identify the server revision, client, upstream version and operations actually exercised.
Public beta · v0.1.0-beta.3. Install from source; the package remains private and is not published to npm.
The host sends API requests to the service configured for this server. Tool results and captured sandbox logs are returned to your MCP client; that client may send them to its configured model provider. Spec caches may be written locally.
Keep .env files and credentials private. Redact account identifiers, IP addresses and
service data before sharing logs or verification reports. See SECURITY.md
for vulnerability reporting.
npm run checkcheck runs lint, formatting, typecheck, mocked tests and the build.
It also verifies the built MCP server version and its two tools without tenant credentials
or upstream network access. npm run cf:check validates the Worker bundle without deploying it. See CONTRIBUTING.md
for the repository layout and contribution checks, and AGENTS.md for
architectural invariants. Live API tests require separate credentials and verification scope.
MIT. Built with TypeScript, the MCP SDK and QuickJS, following the Cloudflare Code Mode pattern.
Run Unraid GraphQL operations by writing JavaScript that uses the unraid.local namespace.
Although the sandbox is JavaScript, the calls below appear synchronous — await is supported and recommended. Each call returns once the host-side HTTP request settles.
Surfaces:
unraid.local.graphql({ query, variables, operationName }) — POST any GraphQL document directly to /graphql. Returns the unwrapped data field.
unraid.local.query.<fieldName>({ args, fields }) — typed query call. args map to GraphQL variables; fields is either a GraphQL selection-set string (no wrapping braces) or a shorthand array of leaf field names. fields is required for non-scalar return types.
unraid.local.mutation.<fieldName>({ args, fields }) — typed mutation call, same rules.
unraid.local.request({ method, path, body, headers }) — raw HTTP escape hatch for endpoints outside GraphQL. Returns { status, body, headers }.
unraid.local.spec — { title, version, sourceUrl, queryCount, mutationCount } for diagnostics.
Operations are async — use await. The final expression is the tool result.
// Read system info via a typed query.
const info = await unraid.local.query.info({
fields: ['os { distro release kernel }', 'versions { unraid api }', 'cpu { manufacturer brand cores }'].join(' '),
});
return info;// List Docker containers with a shorthand selection.
const containers = await unraid.local.query.dockerContainers({
fields: ['id', 'names', 'state', 'status', 'image'],
});
return containers.map(function (c) { return { name: c.names[0], state: c.state }; });// Raw GraphQL document — handy for fragments and aliases.
const data = await unraid.local.graphql({
query: 'query { array { state capacity { kilobytes { free total } } } }',
});
return data;Hard ceiling on API calls per execute; exceeded → error.
Sandbox memory + time bounded.
Credentials never enter the sandbox.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | JavaScript code to execute against the live Unraid GraphQL API. Use await — operations are async. |
Search the Unraid GraphQL schema by writing JavaScript.
The sandbox is read-only — no network. Use this tool to discover what to call before invoking execute.
index — { namespace, title, version, sourceUrl, operations[], types }. Each operation is the compact form: { kind: 'query'|'mutation', namespace: 'local', name, description, args, returnType, returnTypeFields, deprecated }.
unraid.local — same shape as index for parity with the execute tool. May be null if no spec is loaded.
searchOperations(query, limit?) — text-ranked search across name, description, args, and return type.
getOperation(name) — full operation info including arg types and return-type field hints.
findOperationsByName(substring) — list operations whose name contains the substring (case-insensitive).
getType(typeName) — full named-type info (fields for OBJECT/INTERFACE/INPUT_OBJECT, members for UNION, enumValues for ENUM).
console.log() — captured into the tool output.
// All queries that mention "docker"
searchOperations('docker', 20).map(function (op) { return op.name; });// Full detail on the `info` query
getOperation('info');// Inspect the Array type to see its fields
getType('Array');| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | JavaScript code to execute against the operation index. The final expression is returned. |
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0-beta.3executesearchScored across 2 tools
The two tools have clearly distinct purposes: 'execute' runs GraphQL operations, while 'search' explores the schema. There is no overlap, and their descriptions unambiguously differentiate them.
Both tool names are single, lowercase verbs that directly describe their function. Although they lack a verb_noun pattern, they follow a consistent, simple style that is easy to understand.
With only 2 tools, each covers a fundamental aspect of interacting with a GraphQL API: discovery and execution. The count is perfectly scoped for the server's purpose, avoiding unnecessary complexity.
The server provides all necessary functionality: you can explore the schema with 'search' and then execute any discovered operation with 'execute'. There are no obvious gaps in coverage.
The Grafbase MCP server sits in front of a GraphQL API and exposes an MCP protocol-compliant interface that allows AI agents and LLMs to explore and query GraphQL APIs using natural language. It provides tools to search schemas, introspect types and fields, and execute GraphQL queries while minimizing context bloat by returning only relevant schema subsets, with built-in support for authentication, authorization, and configurable access control.
An MCP server that gives your AI access to the source code and docs of all public github repos
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
