<div align="center">

<img src="https://wiro.ai/images/logos/logo/logo.png" alt="Wiro" width="180" />

# Wiro MCP Server

**Official [MCP](https://modelcontextprotocol.io/) server for [Wiro AI](https://wiro.ai/)** — access all AI models on Wiro from Cursor, Claude, Windsurf, and any MCP-compatible AI assistant.

[![npm](https://img.shields.io/badge/npm-@wiro--ai/wiro--mcp-00c38c?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/@wiro-ai/wiro-mcp)
[![MCP](https://img.shields.io/badge/MCP-compatible-333?style=for-the-badge)](https://modelcontextprotocol.io/)
[![MIT](https://img.shields.io/badge/license-MIT-6f42c1?style=for-the-badge)](./LICENSE)

[Official MCP Server](https://wiro.ai/docs/wiro-mcp-server) · [Self-Hosted MCP](https://wiro.ai/docs/mcp-self-hosted) · [Models](https://wiro.ai/models) · [Dashboard](https://wiro.ai/panel) · [Docs](https://wiro.ai/docs)

<img src="https://wiro.ai/images/koala/accent-heavy-koala.png" alt="Wiro Koala mascot" width="60" />

</div>

## Quick Start

Local `npx` and library usage require Node.js 20 or later. The hosted MCP
endpoint does not require a local Node.js installation.

### 1. Get API Keys

Sign up at [wiro.ai](https://wiro.ai/) and create a project at [wiro.ai/panel/project/new](https://wiro.ai/panel/project/new) to get your API key and secret.

### 2. Add to Your AI Assistant

**Cursor** — open MCP settings (`Cmd+Shift+P` → "Open MCP settings") and add:

```json
{
  "mcpServers": {
    "wiro": {
      "command": "npx",
      "args": ["-y", "@wiro-ai/wiro-mcp"],
      "env": {
        "WIRO_API_KEY": "your-api-key",
        "WIRO_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add wiro -- npx -y @wiro-ai/wiro-mcp
```

Then set environment variables `WIRO_API_KEY` and `WIRO_API_SECRET`.

**Claude Desktop** — add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wiro": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@wiro-ai/wiro-mcp"],
      "env": {
        "WIRO_API_KEY": "your-api-key",
        "WIRO_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

**Windsurf** — add to MCP settings:

```json
{
  "mcpServers": {
    "wiro": {
      "command": "npx",
      "args": ["-y", "@wiro-ai/wiro-mcp"],
      "env": {
        "WIRO_API_KEY": "your-api-key",
        "WIRO_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

**OpenClaw** — configure a remote server under `mcp.servers`:

```json
{
  "mcp": {
    "servers": {
      "wiro": {
        "url": "https://mcp.wiro.ai/v1",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "headers": {
          "Authorization": "Bearer ${WIRO_MCP_AUTH}"
        }
      }
    }
  }
}
```

Set `WIRO_MCP_AUTH` in OpenClaw's environment, then verify with
`openclaw mcp doctor wiro --probe`. On older OpenClaw releases without that
probe command, use `openclaw mcp show wiro`, restart OpenClaw, and run
`/tools verbose`.

**Hermes** — add to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  wiro:
    url: "https://mcp.wiro.ai/v1"
    headers:
      Authorization: "Bearer ${WIRO_MCP_AUTH}"
    timeout: 60
    connect_timeout: 10
```

Store `WIRO_MCP_AUTH` in `~/.hermes/.env`, then run `/reload-mcp` and `/tools`.

### 3. Start Using

Ask your AI assistant:

- *"Generate a photorealistic image of a mountain lake at sunset"*
- *"What video generation models are available on Wiro?"*
- *"Show me the parameters for openai/sora-2"*
- *"Create a 5-second video with Kling V3 — a drone shot over mountains"*
- *"Check the status of my last task"*
- *"Show my latest productions and open the newest result"*

## Authentication

Wiro supports two authentication types (chosen when creating a project):

### Signature-Based (Recommended)

More secure. Requires both API key and API secret.

```
WIRO_API_KEY=your-api-key
WIRO_API_SECRET=your-api-secret
```

### API Key Only

Simpler. Only requires the API key. Omit `WIRO_API_SECRET` from your config.

```
WIRO_API_KEY=your-api-key
```

## Available Tools

| Tool | Description |
|------|-------------|
| `search_models` | Search and browse AI models by keyword, category, or owner |
| `get_model_schema` | Get full parameter schema and pricing for any model |
| `recommend_model` | Describe what you want to build, get model recommendations by relevance |
| `explore` | Browse curated models organized by category — no parameters needed |
| `run_model` | Run any model — waits up to 45s by default, then returns a recoverable task token |
| `wait_for_task` | Continue waiting for an existing task without submitting or billing a duplicate run |
| `get_task` | Check task status immediately or wait up to 45s with `wait_seconds` |
| `list_tasks` | Browse authenticated task history across conversations, then continue with `get_task` |
| `get_task_price` | Get the cost of a completed task |
| `cancel_task` | Cancel a queued task |
| `kill_task` | Kill a running task |
| `upload_file` | Upload a file from URL for use as model input |
| `search_docs` | Search the Wiro documentation for guides and API references |

For long generations, `run_model` returns the existing task ID and token when its
wait budget expires. The assistant must continue with `wait_for_task`; retrying
`run_model` creates a separate billable task.

### LLM-friendly responses

All tools publish typed MCP input and output schemas. Successful calls return
`structuredContent` for reliable chaining, concise text `content` for clients
that only render text, and MCP resource links for generated media.
Model parameters remain catalog-driven: `json` and `json-array` fields are sent
as structured values in the same `run_model.params` object as all other inputs.
Use `get_model_schema` as the source of truth for continuation fields.
`previousTaskToken` is the single continuation reference. Send it with exactly
one new `prompt` or non-empty `messages` value for a stateful next turn, or with
`toolOutputs` for a tool-result continuation.

LLM task outputs preserve the public Task Detail segment names and casing:
`thinking`, `answer`, `function_call`, and `custom_tool_call`, including
`call_id`, `finishreason`, and optional normalized token `usage`.
Only validated fields are projected into structured MCP output. When segments
are present, `response` is derived from ordered `answer` segments instead of
raw debug transport; tasks without a typed projection retain their normal
`debugoutput` response.

Completed tool calls return a continuation template in the existing
`nextAction`. Execute each call, replace the output placeholders, and pass the
same ordinary `run_model.params` object back:

```json
{
  "tool": "run_model",
  "arguments": {
    "model": "owner/model",
    "params": {
      "previousTaskToken": "task-token",
      "toolOutputs": [
        {
          "call_id": "call_01",
          "output": "<tool result>"
        }
      ]
    }
  }
}
```

Function calls carry JSON-string `arguments`; custom tool calls carry free-form
`input`. Tool results are request values in `toolOutputs`, not response
segments.

Completed media responses also include an assistant-audience delivery
instruction. Some MCP clients expose a `resource_link` as tool metadata instead
of previewing it inside the tool card, so the assistant is explicitly told to
render images and preserve clickable media links in its user-facing response.
The standard resource link and full-resolution URL remain available to every
client; no base64 media payload is required.

Task responses use the stable states `submitted`, `running`, `completed`,
`failed`, and `cancelled`. When more work is required, the response includes an
executable `nextAction`:

```json
{
  "state": "running",
  "task": {
    "id": "123",
    "token": "task-token",
    "status": "task_start"
  },
  "outputs": [],
  "nextAction": {
    "tool": "wait_for_task",
    "arguments": { "tasktoken": "task-token" },
    "reason": "Continue this exact task. Do not call run_model again."
  }
}
```

Generation chain:
`search_models → get_model_schema → run_model → wait_for_task`

Cross-conversation history:
`list_tasks → get_task`

## Hosted MCP Server

Wiro also provides a hosted MCP server at `https://mcp.wiro.ai/v1` that requires no local installation. See the [MCP Server documentation](https://wiro.ai/docs/wiro-mcp-server) for setup instructions.

## Documentation

- [MCP Server (Hosted)](https://wiro.ai/docs/wiro-mcp-server) — setup guides for Cursor, Claude Code, Claude Desktop, Windsurf, OpenClaw, and Hermes
- [Self-Hosted MCP](https://wiro.ai/docs/mcp-self-hosted) — run locally with npx, environment variables, library usage
- [Authentication](https://wiro.ai/docs/authentication) — signature-based vs API Key Only
- [Run a Model](https://wiro.ai/docs/run-a-model) — how the Run endpoint works
- [Tasks](https://wiro.ai/docs/tasks) — task lifecycle, statuses, determining success
- [Concurrency Limits](https://wiro.ai/docs/concurrency-limits) — concurrent task limits based on balance
- [Error Reference](https://wiro.ai/docs/error-reference) — error codes and handling

## Using as a Library

This package exports its core components for use in custom MCP servers:

```typescript
import { WiroClient } from '@wiro-ai/wiro-mcp/client';
import { createMcpServer } from '@wiro-ai/wiro-mcp/server';

const client = new WiroClient('your-api-key', 'your-api-secret');
const server = createMcpServer(client);
```

### Exports

| Export | Description |
|--------|-------------|
| `createMcpServer(client)` | Creates an McpServer with all 13 tools registered |
| `WiroClient` | API client with both auth types |
| `registerTools(server, client)` | Register tools on an existing McpServer |

```typescript
// Import specific components
import { WiroClient } from '@wiro-ai/wiro-mcp/client';
import { registerTools } from '@wiro-ai/wiro-mcp/tools';
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `WIRO_API_KEY` | Yes | Your Wiro project API key |
| `WIRO_API_SECRET` | No | Your Wiro project API secret (for signature auth) |
| `WIRO_API_BASE_URL` | No | Override API base URL (default: `https://api.wiro.ai/v1`) |

## Links

- [Wiro AI](https://wiro.ai/)
- [Dashboard](https://wiro.ai/panel)
- [Models](https://wiro.ai/models)
- [API Documentation](https://wiro.ai/docs)
- [Create Project](https://wiro.ai/panel/project/new)

## License

MIT — see [LICENSE](./LICENSE) for details.

---

<div align="center">

**Built with ❤️ by the Wiro team**

🌐 [wiro.ai](https://wiro.ai) · [GitHub @wiroai](https://github.com/wiroai)

</div>