# OpenClaw MCP Server

General TypeScript MCP server for OpenClaw tools.

The server is organized around toolsets so new OpenClaw capabilities can be added without recreating MCP startup, transport, and registration boilerplate.

## Structure

```text
src/
  index.ts              # transport startup
  server.ts             # MCP server factory
  toolsets/
    index.ts            # registers all toolsets
    toolset.ts          # shared toolset interface
    core.ts             # base server introspection tools
```

## Install

```bash
npm install
```

## Build

```bash
npm run build
```

## Run

```bash
npm start
```

The server only supports stdio transport and is intended for local MCP clients that spawn the server process.

## Deploy as a STDIO MCP Server

This server is deployed by installing dependencies, building the TypeScript output, and configuring an MCP client to spawn the built stdio entry point.

From the repository directory:

```bash
npm install
npm run build
```

Use `node` with the absolute path to `dist/index.js` as the MCP server command. Example client configuration:

```json
{
  "mcpServers": {
    "openclaw": {
      "command": "node",
      "args": [
        "C:\\Projects\\openclaw-mcp-tools\\dist\\index.js"
      ],
      "env": {
        "ENV_RMAPPI_USER": "email@example.com",
        "ENV_RMAPPI_PASSWORD": "password"
      }
    }
  }
}
```

For a cloned checkout in a different location, replace the `args` path with that checkout's absolute `dist/index.js` path.

For macOS or Linux, the same configuration uses a POSIX path:

```json
{
  "mcpServers": {
    "openclaw": {
      "command": "node",
      "args": [
        "/absolute/path/to/openclaw-mcp-tools/dist/index.js"
      ],
      "env": {
        "ENV_RMAPPI_USER": "email@example.com",
        "ENV_RMAPPI_PASSWORD": "password"
      }
    }
  }
}
```

If using the RMappi/Osuria tools on a fresh machine, also install the Chromium browser binary once:

```bash
npx playwright install chromium
```

After changing TypeScript files, run `npm run build` again before restarting the MCP client. The client owns the server process lifecycle; stop and restart the MCP client to pick up a new build or environment variable changes.

## Inspect

Build first, then run the MCP Inspector against the stdio entry point:

```bash
npm run build
npm run inspect
```

Equivalent direct command:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

Use `dist/index.js`, not `dist/server.js`. The `server.js` file only exports the MCP server factory and does not connect a stdio transport.

## Adding Toolsets

Create a new file in `src/toolsets/`:

```ts
import type { Toolset } from "./toolset.js";

export const myToolset: Toolset = {
  name: "my-toolset",
  description: "Tools for a focused OpenClaw capability.",
  register(server) {
    server.registerTool(
      "openclaw_my_action",
      {
        title: "My Action",
        description: "Does one focused OpenClaw action.",
        inputSchema: {},
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: false
        }
      },
      async () => ({
        content: [{ type: "text", text: "ok" }]
      })
    );
  }
};
```

Then add it to `src/toolsets/index.ts`.

Tool names should use the `openclaw_` prefix and snake_case verbs, for example `openclaw_list_projects` or `openclaw_create_job`.

## RMappi/Osuria Balance Tool

Tool: `openclaw_get_rmappi_balance`

Use this tool when the user asks for RMappi/Osuria saldo, bank balance, available funds, or taloyhtion tilin saldo.

Required environment variables:

```powershell
$env:ENV_RMAPPI_USER = "email@example.com"
$env:ENV_RMAPPI_PASSWORD = "password"
```

Temporary compatibility fallback:

```powershell
$env:ENV_RMAPPI__PASSWORD = "password"
```

The tool does not accept credentials as MCP arguments. It opens `https://app.osuria.com`, accepts the cookie dialog if present, logs in, navigates to `/balance`, reads account cards by visible labels, logs out, and closes the browser.

If Playwright browser binaries are not installed yet, run:

```bash
npx playwright install chromium
```

## RMappi/Osuria Invoices Tool

Tool: `openclaw_get_rmappi_invoices`

Use this tool when the user asks for RMappi/Osuria invoices, laskut, voucher numbers, invoice totals, or invoices for a specific month.

Inputs:

```json
{
  "year": 2026,
  "month": 6
}
```

Both fields are optional. If omitted, the tool uses the current local year and month.

The tool uses the same `ENV_RMAPPI_USER` and `ENV_RMAPPI_PASSWORD` credentials as the balance tool. After login it reads `sessionStorage["x-session-token"]`, calls the RMappi invoices API with that token, returns the API JSON array, logs out, and closes the browser. The token is never returned in tool output.