open-index/open-npm huggingface dataset:
npm package: @happyrobot-ai/mcp-twin
Description: HappyRobot Twin Database MCP Server - Explore schemas, run queries, and manage tables via Claude Code or any MCP client
Author: HappyRobot
Latest version: 0.1.0

# @happyrobot-ai/mcp-twin

A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for managing your HappyRobot Twin database. Explore schemas, run queries, and manage tables from Claude Desktop, Claude Code, or any MCP-compatible client.

## Quick Start

### Claude Code

```bash
claude mcp add -s user happyrobot-twin -- npx @happyrobot-ai/mcp-twin
```

Or with the API key pre-configured:

```bash
claude mcp add -s user happyrobot-twin -e HAPPYROBOT_API_KEY=sk_live_xxx -- npx @happyrobot-ai/mcp-twin
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "happyrobot-twin": {
      "command": "npx",
      "args": ["@happyrobot-ai/mcp-twin"],
      "env": {
        "HAPPYROBOT_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

### `.mcp.json` (project-level)

```json
{
  "mcpServers": {
    "happyrobot-twin": {
      "command": "npx",
      "args": ["@happyrobot-ai/mcp-twin"],
      "env": {
        "HAPPYROBOT_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

## Configuration

| Variable | Description | Default |
|---|---|---|
| `HAPPYROBOT_API_KEY` | Your API key (`sk_live_*` or `sk_test_*`) | _(none, required)_ |

If the API key is not set via environment variable, use the `setup` tool at runtime to provide it.

## Available Tools

| Tool | Description |
|---|---|
| `setup` | Configure your API key at runtime |
| `get_schema` | List all tables and views with columns, types, and primary keys |
| `get_table_data` | Fetch rows from a table with pagination |
| `create_table` | Create a new table with typed columns |
| `execute_sql` | Run arbitrary SQL (SELECT, INSERT, UPDATE, DELETE, DDL) |
| `insert_row` | Insert a single row into a table |
| `update_row` | Update rows matching a WHERE clause |
| `delete_rows` | Delete rows from a table by primary key |
| `drop_table` | Drop a table permanently |

### Limits

- SQL queries have a **5-second timeout**
- SELECT results are capped at **500 rows** / **1 MB**

## Development

```bash
# Install dependencies
npm install

# Run in development mode
HAPPYROBOT_API_KEY=sk_test_xxx npm run dev

# Build for production
npm run build
```

## License

MIT