{"id":51017711,"url":"https://github.com/runapi-ai/mcp","last_synced_at":"2026-06-22T00:00:47.093Z","repository":{"id":362267292,"uuid":"1258122081","full_name":"runapi-ai/mcp","owner":"runapi-ai","description":"RunAPI MCP server for model discovery, pricing lookup, task creation, and LLM chat.","archived":false,"fork":false,"pushed_at":"2026-06-18T09:30:54.000Z","size":383,"stargazers_count":46,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T10:24:59.128Z","etag":null,"topics":["ai","claude-code","codex","cursor","image-generation","llm","mcp","mcp-server","music-generation","runapi","video-generation"],"latest_commit_sha":null,"homepage":"https://runapi.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/runapi-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-03T09:43:06.000Z","updated_at":"2026-06-18T09:30:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/runapi-ai/mcp","commit_stats":null,"previous_names":["runapi-ai/mcp"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/runapi-ai/mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runapi-ai%2Fmcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runapi-ai%2Fmcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runapi-ai%2Fmcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runapi-ai%2Fmcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/runapi-ai","download_url":"https://codeload.github.com/runapi-ai/mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runapi-ai%2Fmcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34629658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude-code","codex","cursor","image-generation","llm","mcp","mcp-server","music-generation","runapi","video-generation"],"created_at":"2026-06-21T13:00:25.697Z","updated_at":"2026-06-22T00:00:47.076Z","avatar_url":"https://github.com/runapi-ai.png","language":"TypeScript","funding_links":[],"categories":["MCP Support","Servers","Containerised MCP Servers"],"sub_categories":["MCP Servers","AI \u0026 ML","AI \u0026 Machine Learning"],"readme":"\u003ch1 align=\"center\"\u003eRunAPI MCP Server\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAI image generation, video generation, music creation, text-to-speech, prompt search, and model discovery — 130+ models from Flux, Kling, Seedance, Veo, Suno, ElevenLabs, Claude, GPT, Gemini, and 18 providers in one MCP server.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eWorks with Claude Code, Codex, Cursor, Windsurf, VS Code, Roo Code, and any MCP-compatible host.\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@runapi.ai/mcp\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/%40runapi.ai/mcp?style=flat-square\u0026color=blue\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square\" alt=\"Apache-2.0 license\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Type-MCP_Server-blue?style=flat-square\" alt=\"MCP Server\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Models-130+-green?style=flat-square\" alt=\"130+ models\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e |\n  \u003ca href=\"#tools\"\u003eTools\u003c/a\u003e |\n  \u003ca href=\"#examples\"\u003eExamples\u003c/a\u003e |\n  \u003ca href=\"#catalog-coverage\"\u003eCatalog\u003c/a\u003e |\n  \u003ca href=\"#platform-setup\"\u003ePlatforms\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What Is This?\n\nRunAPI MCP Server connects MCP-compatible coding tools to RunAPI.\nIt lets an assistant browse the RunAPI catalog, inspect model inputs, check current pricing snapshots, create media tasks, poll task status, and check account balance.\n\nThe discovery tools work without an API key because they use the embedded build-time catalog.\nAuthenticated operations require `RUNAPI_API_KEY`.\n\nThis package is a pure client.\nIt does not run a local generation backend and does not require changes to your RunAPI account beyond creating an API key for authenticated tools.\n\n---\n\n## Quick Start\n\nFor Claude Code, Cursor, Windsurf, and VS Code, install RunAPI with Claude Code's MCP command:\n\n```bash\nclaude mcp add runapi -s user -- npx -y @runapi.ai/mcp\n```\n\nThe scope flag controls where the MCP server is stored:\n\n- `-s user`: global, available in all projects for your user.\n- `-s project`: team-shared, written to `.mcp.json` in the current repo so it can be committed.\n\nUse project scope when you want the whole team to share the same server config:\n\n```bash\nclaude mcp add runapi -s project -- npx -y @runapi.ai/mcp\n```\n\nCompatibility fallback for non-Claude Code platforms or manual JSON config:\n\n```json\n{\n  \"mcpServers\": {\n    \"runapi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@runapi.ai/mcp\"],\n      \"env\": {\n        \"RUNAPI_API_KEY\": \"${RUNAPI_API_KEY}\"\n      }\n    }\n  }\n}\n```\n\nIf your host needs a generated config file, use the legacy `init` command as a fallback:\n\n```bash\nnpx @runapi.ai/mcp init claude\nnpx @runapi.ai/mcp init cursor\nnpx @runapi.ai/mcp init vscode\nnpx @runapi.ai/mcp init windsurf\nnpx @runapi.ai/mcp init roo\n```\n\nFree catalog tools work even when `RUNAPI_API_KEY` is not configured.\nFor task creation and balance checks, create an API key in the RunAPI dashboard and expose it as `RUNAPI_API_KEY`.\n\n---\n\n## Tools\n\n| Tool | Auth | Purpose |\n|---|---|---|\n| `list_models` | No | List RunAPI models from the embedded catalog. Supports `modality`, `service`, and `action` filters. |\n| `get_model_info` | No | Return service, action, modality, input constraints, and pricing snapshot for a model slug. Use `service` + `action` when a model appears in multiple endpoints. |\n| `list_actions` | No | Group endpoint action names by modality. |\n| `check_pricing` | No | Return pricing snapshot data for a `service` + `action` + `model` combination. |\n| `search_prompts` | No | Search reusable prompt examples by `modality`, `category`, `tags`, `q`, `model`, `featured`, and pagination. |\n| `create_task` | Yes | Create a media task and optionally poll until completion. |\n| `get_task` | Yes | Fetch status and latest payload for an existing media task. |\n| `check_balance` | Yes | Return account balance and spending metrics. |\n\nThe catalog, pricing, and prompt search tools are designed for funnel-top discovery inside coding tools.\nThe task and balance tools are designed for authenticated workflows.\n\n---\n\n## Examples\n\nAsk your assistant natural-language questions.\nThe assistant should use the tools to discover current model slugs and pricing instead of relying on memorized names.\n\n### Browse The Catalog\n\n```text\nWhat RunAPI image models are available?\n```\n\nExpected behavior:\n\n1. The assistant calls `list_models` with `modality: \"image\"`.\n2. It summarizes the returned model slugs, services, actions, and required fields.\n3. It avoids quoting stale prices unless it calls `check_pricing`.\n\n### Search Prompt Examples\n\n```text\nFind image prompt examples for a logo.\n```\n\nExpected behavior:\n\n1. The assistant calls `search_prompts` with `modality: \"image\"` and `q: \"logo\"`.\n2. It summarizes returned titles, prompt text, model slugs, categories, and tags.\n3. It uses the selected prompt with `get_model_info` before creating a task.\n\n### Inspect A Model\n\n```text\nShow me the required parameters for this model slug: \u003cmodel-slug\u003e\n```\n\nExpected behavior:\n\n1. The assistant calls `get_model_info`.\n2. If the response is ambiguous, it chooses the relevant service/action from the returned matches and calls `get_model_info` again with `service` and `action`.\n3. It shows required fields, enum constraints, range constraints, conditional input rules, supported action, and pricing snapshot if present.\n4. It tells you to choose another slug with `list_models` if the slug is not found.\n\n### Create A Media Task\n\n```text\nGenerate a square product image with RunAPI. Pick a suitable image model.\n```\n\nExpected behavior:\n\n1. The assistant calls `list_models` to choose a compatible image model.\n2. It calls `get_model_info` with the selected service/action/model to validate parameters and any conditional input rules.\n3. It asks for confirmation if the request is expensive, long-running, or a batch.\n4. It calls `create_task`.\n5. It returns task ID, status, output URLs, and cost fields when available.\n\n### Submit Without Waiting\n\n```text\nCreate the task but do not wait for completion.\n```\n\nExpected behavior:\n\n1. The assistant calls `create_task` with `wait: false`.\n2. It returns the task ID.\n3. You can later ask for status with `get_task`.\n\n### Check Account Balance\n\n```text\nCheck my RunAPI balance.\n```\n\nExpected behavior:\n\n1. The assistant calls `check_balance`.\n2. If no key is configured, it explains how to set `RUNAPI_API_KEY`.\n\n## Catalog Coverage\n\nThe embedded catalog is generated from RunAPI's contract snapshot.\nIt includes media models, utility endpoints, and LLM model slugs for discovery.\n\n| Modality | What To Use |\n|---|---|\n| Image | `list_models` with `modality: \"image\"` |\n| Video | `list_models` with `modality: \"video\"` |\n| Audio and music | `list_models` with `modality: \"audio\"` |\n| LLM | `list_models` with `modality: \"llm\"` |\n| Utility | `list_models` with `modality: \"utility\"` |\n\nCatalog contents can change between releases.\nUse `list_models` for current service/action/model slugs and `get_model_info` for each model's current constraints.\nFor LLM inference, connect through the RunAPI API or SDK directly.\n\n---\n\n## Pricing\n\nRunAPI pricing is exposed through the `check_pricing` tool and the public pricing page.\nDo not rely on examples in README files for exact prices.\n\nUseful flows:\n\n1. Call `list_models` to find a candidate model.\n2. Call `check_pricing` with `service`, `action`, and `model`.\n3. Show the returned pricing snapshot or link to [runapi.ai/pricing](https://runapi.ai/pricing).\n\nFree catalog tools do not create tasks and do not consume account balance.\n\n---\n\n## Platform Setup\n\n### Claude Code, Cursor, Windsurf, And VS Code\n\nRun:\n\n```bash\nclaude mcp add runapi -s user -- npx -y @runapi.ai/mcp\n```\n\nUse `-s user` for a global install available in all projects.\nUse `-s project` when you want Claude Code to write `.mcp.json` in the repo for team-shared config.\n\nRestart or reload your MCP host after changing MCP configuration.\n\n### Compatibility Fallback: Generated Config\n\nUse `init` only when a host needs a platform-specific JSON file or cannot use the Claude Code MCP command.\n\nClaude Code fallback:\n\n```bash\nnpx @runapi.ai/mcp init claude\n```\n\nThis writes `.mcp.json` in the current directory.\n\nCursor fallback:\n\n```bash\nnpx @runapi.ai/mcp init cursor\n```\n\nThis writes `.cursor/mcp.json`.\nOpen Cursor settings to verify the MCP server is enabled.\n\nVS Code fallback:\n\n```bash\nnpx @runapi.ai/mcp init vscode\n```\n\nThis writes `.vscode/mcp.json`.\nVS Code uses a top-level `servers` key and `type: \"stdio\"` in generated config.\n\nWindsurf fallback:\n\n```bash\nnpx @runapi.ai/mcp init windsurf\n```\n\nThis writes the generated config for the Windsurf target used by the init command.\n\n### Roo Code\n\nRun:\n\n```bash\nnpx @runapi.ai/mcp init roo\n```\n\nThis writes `.roo/mcp.json`.\n\n### Manual Configuration\n\nUse the example files in `examples/` as starting points.\nEach platform has slightly different wrapper keys and file paths, but all run the same command:\n\n```bash\nnpx -y @runapi.ai/mcp\n```\n\n---\n\n## Configuration\n\nThe server reads configuration in this order:\n\n1. `RUNAPI_API_KEY` environment variable\n2. `~/.config/runapi/config.json`\n3. No key, which still allows free catalog tools\n\nExample config file:\n\n```json\n{\n  \"apiKey\": \"your_runapi_key\"\n}\n```\n\nYou can also set a custom base URL for local testing:\n\n```json\n{\n  \"apiKey\": \"your_runapi_key\",\n  \"baseUrl\": \"https://runapi.ai\"\n}\n```\n\nDo not commit real API keys.\n\n---\n\n## Data Sync\n\nThis package ships build-time data files:\n\n- `data/contract.json`: catalog, actions, model slugs, and input constraints\n- `data/pricing.json`: pricing snapshot used by `check_pricing`\n\nRefresh data from the RunAPI source tree before a release:\n\n```bash\nnpm run sync:data\n```\n\nBuild-time data means a pricing or catalog update requires a new package release.\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck\nnpm test\nnpm pack --dry-run\n```\n\nRun the server locally:\n\n```bash\nnpm run dev\n```\n\nManual initialize smoke test:\n\n```bash\nprintf '%s\\n' '{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"0.1.0\"}},\"id\":1}' | npx tsx src/index.ts\n```\n\n---\n\n## Package Contents\n\nThe npm package includes:\n\n- compiled `dist/` files\n- embedded `data/` files\n- platform examples\n- eval scenarios, when generated by this repo\n- README, changelog, license, and package metadata\n\nIt does not include `node_modules`, `.env`, local config files, or API keys.\n\n---\n\n## Also Available Via CLI\n\nRunAPI also has a separate command-line client for terminal workflows.\nUse this MCP server when you want RunAPI available inside an MCP host.\nUse the CLI when you want direct shell commands, scripts, or CI integration.\n\n---\n\n## License\n\nLicensed under the [Apache License, Version 2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunapi-ai%2Fmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frunapi-ai%2Fmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunapi-ai%2Fmcp/lists"}