Stackrun

Universal CLI to install, authenticate, and execute SaaS tools from terminal.

Built for developers and AI agents that need to interact with external APIs without wrappers or SDKs.

How it works

Each SaaS tool is described by a declarative JSON manifest (URL, auth, endpoints). Stackrun handles the full flow: search tools in a registry, install them, store tokens, and execute HTTP calls.

stackrun search stripe                              # find tools in the registry
stackrun install stripe                             # download the manifest
stackrun login stripe                               # store your API key
stackrun call stripe list_customers --limit 10      # execute the API call
stackrun schema stripe                              # see available commands
stackrun uninstall stripe                           # remove the tool
stackrun logout stripe                              # remove stored token

Install

npm install -g @nico0891/stackrun

Then run:

stackrun --help

Quick Start

stackrun search stripe                              # find tools
stackrun install stripe                             # install manifest
stackrun login stripe --token sk_test_xxx           # store API key
stackrun call stripe list_customers --limit 5       # make the call
stackrun call stripe list_customers --json | jq .   # pipe JSON output

Available Tools

| Tool | Description | |------|-------------| | stripe | Stripe payments API | | github | GitHub REST API | | notion | Notion workspace API | | slack | Slack messaging API | | hubspot | HubSpot CRM API | | sendgrid | SendGrid email API | | linear | Linear project management API |

Run stackrun search to see all available tools.

Agent Mode

Stackrun is designed for AI agents. Use --agent or --json for machine-readable output:

stackrun search --agent                    # JSON, no spinners, no color
stackrun call stripe list_customers --json # clean JSON to stdout
stackrun schema stripe --json              # discover commands programmatically

Pipe detection is automatic: when stdout is not a TTY, output defaults to JSON.

MCP Server

Stackrun works as an MCP server. One Stackrun MCP server replaces N individual API servers — every installed tool becomes native tool calls for your AI agent.

stackrun mcp              # start the MCP server (stdio)
stackrun mcp --list       # preview which tools would be exposed

Each manifest command is exposed as <tool>_<command> (e.g., stripe_list_customers, github_get_user).

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "stackrun": {
      "command": "stackrun",
      "args": ["mcp"]
    }
  }
}

Claude Code

claude mcp add stackrun -- stackrun mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "stackrun": {
      "command": "stackrun",
      "args": ["mcp"]
    }
  }
}

Then install tools and authenticate — the agent can call them immediately:

stackrun install stripe && stackrun login stripe --token sk_test_xxx
# Now your agent can use stripe_list_customers, stripe_create_customer, etc.

Development

# Clone the repo
git clone https://github.com/nico150891/stackrun.git
cd stackrun
npm install

# Scripts
npm run dev         # run with ts-node
npm run build       # compile to dist/
npm test            # run tests (vitest)
npm run lint        # eslint
npm run format      # prettier
npm run typecheck   # tsc --noEmit

Project Structure

src/
├── commands/       # CLI commands (search, install, uninstall, login, logout, call, list, schema, mcp)
├── mcp/            # MCP server and tool call handler
├── services/       # Business logic (registry, auth, executor, storage, validator)
├── types/          # TypeScript type definitions
└── index.ts        # Entry point

registry/           # Tool manifests (JSON) — the MVP registry
tests/              # Unit and integration tests
docs/               # Plans, decisions, notes

Adding a New Tool

Create a JSON manifest in registry/ following the schema:

{
  "name": "tool-name",
  "version": "1.0.0",
  "description": "What it does",
  "base_url": "https://api.example.com/v1",
  "auth": { "type": "bearer", "header": "Authorization", "prefix": "Bearer" },
  "headers": { "X-Api-Version": "2024-01-01" },
  "commands": [
    {
      "name": "list_items",
      "method": "GET",
      "path": "/items",
      "description": "List all items",
      "params": [
        { "name": "limit", "description": "Max results", "required": false, "location": "query", "type": "number" }
      ]
    }
  ]
}

Then add it to registry/index.json.

License

MIT