# shelby-mcp

MCP server for [Shelby Protocol](https://shelby.xyz) — connect AI agents to decentralized storage.

Works with **Claude Desktop**, **Cursor**, **Claude Code**, **Codex**, and any MCP-compatible client.

## What it does

AI agents can read, write, and manage files on Shelby's decentralized storage network (Aptos) through 5 tools:

| Tool | Description |
|------|-------------|
| `shelby_upload` | Upload text content to Shelby storage |
| `shelby_download` | Download a blob and return its content |
| `shelby_list` | List blobs under current account |
| `shelby_delete` | Delete a blob |
| `shelby_account` | Show account info, balance, network |

## Prerequisites

- [Node.js](https://nodejs.org) v18+
- [Shelby CLI](https://docs.shelby.xyz) installed and configured (`npm install -g @shelby-protocol/cli`)
- A funded Shelby account (`shelby faucet`)

## Install

```bash
git clone https://github.com/Jasekeee/shelby-mcp.git
cd shelby-mcp
npm install
npm run build
```

## Use with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "shelby": {
      "command": "node",
      "args": ["/absolute/path/to/shelby-mcp/build/index.js"]
    }
  }
}
```

Restart Claude Desktop. You can now say:

> "Upload this report to Shelby as reports/q1-2026.txt"
>
> "Download my config from Shelby"
>
> "What's my Shelby account balance?"

## Use with Cursor

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

```json
{
  "mcpServers": {
    "shelby": {
      "command": "node",
      "args": ["/absolute/path/to/shelby-mcp/build/index.js"]
    }
  }
}
```

## Use with Claude Code

```bash
claude mcp add shelby node /absolute/path/to/shelby-mcp/build/index.js
```

## Architecture

```
AI Agent (Claude/Cursor/Codex)
    ↕ MCP Protocol (stdio)
shelby-mcp server
    ↕ CLI wrapper
shelby CLI → Aptos blockchain → Shelby storage network
```

The server wraps the `shelby` CLI rather than using the SDK directly. This ensures compatibility across CLI versions and avoids SDK breaking changes.

## Configuration

shelby-mcp reads from your existing `~/.shelby/config.yaml`. No additional configuration needed — if `shelby upload` works in your terminal, it works through MCP.

## Contributing

PRs welcome. Please open an issue first for major changes.

## License

MIT

## Links

- [Shelby Protocol](https://shelby.xyz)
- [Shelby Docs](https://docs.shelby.xyz)
- [Shelby GitHub](https://github.com/shelby)
- [MCP Specification](https://modelcontextprotocol.io)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)