npm package: @runstream/mcp
Description: Runstream MCP server — push and pull artifacts from AI assistants (Claude Desktop, ChatGPT, Cursor)
Latest version: 0.1.0

# Runstream MCP Server

MCP (Model Context Protocol) server that lets AI assistants (Claude Desktop, ChatGPT, Cursor, etc.) interact with Runstream projects and artifacts.

## Quick Setup

### 1. Get your credentials

Go to [app.runstream.ai/settings/api-keys](https://app.runstream.ai/settings/api-keys) and create an API key. You need two values:

| Variable | Where to get it |
|----------|----------------|
| `RUNSTREAM_API_KEY` | Settings > API Keys — create a new key |
| `RUNSTREAM_ORG_ID` | Settings > Organization — your org ID |

### 2. Configure your AI client

#### Claude Desktop

1. Open Claude Desktop > Settings > Developer > Edit Config
2. Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "runstream": {
      "command": "npx",
      "args": ["-y", "@runstream/mcp@latest"],
      "env": {
        "RUNSTREAM_API_KEY": "your-api-key",
        "RUNSTREAM_ORG_ID": "your-org-uuid"
      }
    }
  }
}
```

3. Restart Claude Desktop.

Once configured, you'll see guided prompts in the "/" menu:

- **Start Runstream** — List projects, pick one, see existing artifacts
- **Create PRD** — Draft a PRD and push it to a project
- **Continue Working** — Review artifacts and pick up where you left off

#### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "runstream": {
      "command": "npx",
      "args": ["-y", "@runstream/mcp@latest"],
      "env": {
        "RUNSTREAM_API_KEY": "your-api-key",
        "RUNSTREAM_ORG_ID": "your-org-uuid"
      }
    }
  }
}
```

#### ChatGPT

ChatGPT doesn't support MCP prompts, but the tools work the same way. Connect the MCP server and use natural language:

- "List my Runstream projects"
- "Show me the artifacts in project X"
- "Create a PRD for [feature] and push it to project X"

### Optional env vars

| Variable | Purpose |
|----------|---------|
| `RUNSTREAM_API_URL` | Override the API URL (defaults to `https://api.runstream.ai`) |

## Available Tools

| Tool | Description |
|------|-------------|
| `list_projects` | List all projects in your organization |
| `list_artifacts` | List artifacts in a project (optionally filter by status) |
| `get_artifact` | Get a single artifact with full content |
| `push_artifact` | Create a new artifact (PRD, spec, stories, etc.) |
| `update_artifact` | Update an existing artifact |
| `get_project_context` | Get project details + all published/approved artifacts |

## Developer Setup (Full Server)

For developers who need the full MCP server with GitHub, review, deploy, and plan tools (from the monorepo):

```json
{
  "mcpServers": {
    "runstream": {
      "command": "node",
      "args": ["/path/to/runstream/services/mcp/dist/index.js"],
      "env": {
        "RUNSTREAM_API_KEY": "your-api-key",
        "RUNSTREAM_ORG_ID": "your-org-uuid",
        "GITHUB_TOKEN": "your-github-pat",
        "ANTHROPIC_API_KEY": "your-anthropic-key"
      }
    }
  }
}
```

This requires cloning the monorepo and building:

```bash
pnpm install && pnpm --filter @runstream/mcp build
```

## Development

```bash
# Build TypeScript (full server)
pnpm --filter @runstream/mcp build

# Bundle standalone for npm
pnpm --filter @runstream/mcp bundle

# Dev mode (auto-reload)
pnpm --filter @runstream/mcp dev
```

## Troubleshooting

**"RUNSTREAM_API_KEY is required"**
- Make sure `RUNSTREAM_API_KEY` is set in your config's `env` block.
- Get a key from [app.runstream.ai/settings/api-keys](https://app.runstream.ai/settings/api-keys).

**Tools not appearing?**
- Restart Claude Desktop after config changes.
- Check Claude Desktop logs for error messages.

**API errors (401, 403)?**
- Check that your API key is valid and not expired.
- Check that your `RUNSTREAM_ORG_ID` matches the org the key belongs to.