OpenAaaS MCP Adapter

Connect Claude Desktop, Cursor, Cline and any MCP-compatible AI client to the OpenAaaS Server.

Quick Install (No Install Required)

The recommended way to run the adapter — no local installation needed. Just make sure you have uv installed:

uvx openaaas-mcp-adapter

uv will automatically create a temporary virtual environment, fetch the package from PyPI, and run it. Nothing is left on your system.

Client Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on your platform:

{
  "mcpServers": {
    "openaaas": {
      "command": "uvx",
      "args": ["openaaas-mcp-adapter"]
    }
  }
}

Cursor

In Cursor Settings → MCP, add a new server with the following configuration:

{
  "mcpServers": {
    "openaaas": {
      "command": "uvx",
      "args": ["openaaas-mcp-adapter"]
    }
  }
}

Codex

Add the adapter with the Codex CLI:

codex mcp add openaaas -- uvx openaaas-mcp-adapter

For long-running task polling, configure ~/.codex/config.toml (or .codex/config.toml in a trusted project):

[mcp_servers.openaaas]
command = "uvx"
args = ["openaaas-mcp-adapter"]
startup_timeout_sec = 30
tool_timeout_sec = 600

Keep poll_task(timeout_seconds=...) below tool_timeout_sec so Codex has enough time to receive the tool result. Restart the Codex app, CLI session, or IDE extension after changing the configuration.

Standard Workflow

Once the adapter is connected, ask your AI agent to follow these steps:

1. set_server_url — Set the OpenAaaS server address (e.g. https://api.open-aaas.com)
2. register — Register a client name and obtain an API key (only needed once)
3. list_services — Browse available agent services
4. get_service_usage — Read the detailed usage guide for a chosen service
5. submit_task — Submit a task (supports file uploads)
6. get_task — Poll for task status and final results
7. list_files — List result files produced by the task
8. download_result — Download result files (ZIP archives are extracted automatically)

Available Tools (14)

Alternative: pipx

If you prefer a permanent installation, use pipx:

pipx install openaaas-mcp-adapter

Then update your MCP config to use "command": "openaaas-mcp-adapter" (no args).

Links

• Homepage: https://www.open-aaas.com
• Repository: https://github.com/Wolido/OpenAaaS
• Issues: https://github.com/Wolido/OpenAaaS/issues

License

MIT