Risha.ai MCP Server

A Model Context Protocol (MCP) server for the Risha.ai API.

This server lets MCP clients such as Codex, Claude Code, and Claude Desktop discover Risha API operations, authenticate with email/password, inspect capabilities, check credit balance and create generation requests.

Features

• Email/password authentication using Risha /auth/login/

• Automatic login at MCP startup

• Automatic startup context loading:

  • current user

  • active capabilities

  • credit wallet / balance

• Generic Swagger-backed API caller for all Risha operations

• Convenience generation helpers:

  • risha_generate_image

  • risha_create_generation

• Automatic polling for generation completion

Related MCP server: Stellastra MCP Server

Requirements

• Node.js 18+

• A valid Risha.ai account (www.risha.ai)

• An MCP-capable client, for example:

  • Codex

  • Claude Code

  • Claude Desktop

Install

git clone https://github.com/aimedialab/risha-mcp-server.git
cd risha-mcp-server
npm install

Environment variables

Required for email/password login:

RISHA_EMAIL="you@example.com"
RISHA_PASSWORD="your-password"

Optional:

RISHA_API_BASE_URL="https://adminxcore-api.risha.ai/api"

Token-based auth is also supported, but email/password is the recommended flow:

RISHA_API_TOKEN="your-access-token"
RISHA_REFRESH_TOKEN="your-refresh-token"

Never commit real credentials. Put them in your MCP client config or a local .env file. .env is ignored by git.

Run manually

RISHA_EMAIL="you@example.com" RISHA_PASSWORD="your-password" npm start

Expected startup log:

[risha-mcp] logged in, loaded 32 capabilities, credit balance: 72621

An MCP stdio server normally waits silently after startup. That is expected.

Available MCP tools

risha_api_info

Shows API metadata, authentication mode, startup status, capabilities count, credit balance, and Swagger tag list.

risha_startup_state

Shows the context loaded at startup:

• login state

• current user

• capabilities count

• credit balance

• startup errors, if any

risha_capabilities

Returns the active capabilities retrieved at startup.

Input example:

{
  "filter": "image",
  "limit": 20
}

risha_credit_balance

Returns credit balance, wallet, summary, and user wallet data.

risha_refresh_context

Logs in again and refreshes current user, capabilities, and credit data.

risha_login

Manually logs in with RISHA_EMAIL and RISHA_PASSWORD and caches the JWT for the current MCP session.

risha_list_operations

Searches all Swagger operations.

Input example:

{
  "filter": "generation",
  "limit": 20
}

risha_get_operation

Returns schema details for one operation.

Input example:

{
  "operationId": "generation-requests_create"
}

risha_call

Generic caller for any Swagger operation.

Input example:

{
  "operationId": "auth_me"
}

Generation request example:

{
  "operationId": "generation-requests_create",
  "body": {
    "capability": 21,
    "title": "MCP smoke test",
    "prompt_data": {
      "prompt": "a red apple on a white table",
      "resolution": "0.5k",
      "aspect_ratio": "1:1"
    }
  }
}

risha_create_generation

Creates any generation request and optionally polls until it reaches a terminal state.

Input example:

{
  "capability": 21,
  "title": "MCP image test",
  "prompt_data": {
    "prompt": "a red apple on a white table",
    "resolution": "0.5k",
    "aspect_ratio": "1:1"
  },
  "wait": true,
  "timeoutSeconds": 300,
  "pollSeconds": 5
}

risha_generate_image

Convenience text-to-image tool. Defaults to capability 21, 0.5k, 1:1.

Input example:

{
  "prompt": "a cinematic photo of a red apple on a white table",
  "resolution": "0.5k",
  "aspect_ratio": "1:1",
  "timeoutSeconds": 300,
  "pollSeconds": 5
}

risha_resolve_media_url

Converts a private authenticated Risha media URL into a signed public CDN URL.

Input example:

{
  "url": "https://adminxcore-api.risha.ai/api/media/asset/4c6cbe1c-7696-4c13-8790-6456e5d64698/?f=webp&h=600&q=85&w=600"
}

Use with Codex

Codex reads MCP servers from ~/.codex/config.toml.

Add this block:

[mcp_servers.risha]
command = "node"
args = ["/absolute/path/to/risha-mcp-server/src/index.js"]
startup_timeout_sec = 60

[mcp_servers.risha.env]
RISHA_EMAIL = "you@example.com"
RISHA_PASSWORD = "your-password"

For the local project path created by this agent:

[mcp_servers.risha]
command = "node"
args = ["/Users/amirhamdani/Documents/risha-mcp-server/src/index.js"]
startup_timeout_sec = 60

[mcp_servers.risha.env]
RISHA_EMAIL = "you@example.com"
RISHA_PASSWORD = "your-password"

Restart Codex after editing the config.

Codex test prompts

Use the Risha MCP server and run risha_api_info.

Use the Risha MCP server and show my Risha credit balance.

Use the Risha MCP server and list image capabilities.

Use Risha MCP to generate a small image of a red apple on a white table.

Use with Claude Code

Claude Code supports MCP servers over stdio. You can add the server using either the CLI or JSON configuration.

Option A: Claude Code CLI

From the project directory:

claude mcp add risha \
  --env RISHA_EMAIL="you@example.com" \
  --env RISHA_PASSWORD="your-password" \
  -- node /absolute/path/to/risha-mcp-server/src/index.js

Then restart Claude Code or start a new session.

Test prompts:

Use the risha MCP server and run risha_api_info.

Use the risha MCP server to show my credit balance.

Use the risha MCP server to generate a small image of a robot holding a camera.

Option B: Claude MCP JSON config

If your Claude Code setup uses JSON MCP configuration, add:

{
  "mcpServers": {
    "risha": {
      "command": "node",
      "args": ["/absolute/path/to/risha-mcp-server/src/index.js"],
      "env": {
        "RISHA_EMAIL": "you@example.com",
        "RISHA_PASSWORD": "your-password"
      }
    }
  }
}

Use with Claude Desktop

Add this to your Claude Desktop MCP config:

{
  "mcpServers": {
    "risha": {
      "command": "node",
      "args": ["/absolute/path/to/risha-mcp-server/src/index.js"],
      "env": {
        "RISHA_EMAIL": "you@example.com",
        "RISHA_PASSWORD": "your-password"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Test with MCP Inspector

cd risha-mcp-server
npx @modelcontextprotocol/inspector \
  env RISHA_EMAIL="you@example.com" RISHA_PASSWORD="your-password" \
  node src/index.js

Open the Inspector URL printed in the terminal and try:

1. risha_api_info

2. risha_credit_balance

3. risha_capabilities

4. risha_generate_image

Typical workflow for agents

1. Call risha_api_info to confirm authentication and startup state.

2. Call risha_credit_balance to check credits.

3. Call risha_capabilities to pick a capability.

4. Use risha_generate_image for simple image generation, or risha_create_generation for arbitrary capabilities.

5. Use returned public CDN URLs directly. Private media URLs are resolved automatically when possible.

Notes on generation time

Image/video generation is asynchronous. The MCP server can create a request immediately, but final completion depends on provider queue and model runtime. risha_generate_image and risha_create_generation poll until completion or timeout.

Default polling values:

• timeoutSeconds: 300

• pollSeconds: 5

Development

npm install
node --check src/index.js
npm start

Project layout:

risha-mcp-server/
  src/
    index.js       # MCP server implementation
    swagger.json   # Risha Swagger/OpenAPI document
  package.json
  README.md

License

MIT