# BagOS MCP server

> An MCP server that lets an AI assistant analyze Solana token data and execute gated swaps or claim creator fees on the Bags platform.

- Repository: https://github.com/edycutjong/bagos
- Page: https://hostedmcp.org/servers/edycutjong/bagos
- Transport: stdio
- Stars: 1
- License: MIT
- Latest version: 3.0.7

## Install

### Claude Code

```sh
claude mcp add --env 'BAGS_API_KEY=<YOUR_BAGS_API_KEY>' --env 'SOLANA_RPC_URL=<YOUR_SOLANA_RPC_URL>' bagos -- npx -y bagos-mcp-server
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "bagos": {
      "command": "npx",
      "args": [
        "-y",
        "bagos-mcp-server"
      ],
      "env": {
        "BAGS_API_KEY": "<YOUR_BAGS_API_KEY>",
        "SOLANA_RPC_URL": "<YOUR_SOLANA_RPC_URL>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "bagos": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "bagos-mcp-server"
      ],
      "env": {
        "BAGS_API_KEY": "<YOUR_BAGS_API_KEY>",
        "SOLANA_RPC_URL": "<YOUR_SOLANA_RPC_URL>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"bagos","type":"stdio","command":"npx","args":["-y","bagos-mcp-server"],"env":{"BAGS_API_KEY":"<YOUR_BAGS_API_KEY>","SOLANA_RPC_URL":"<YOUR_SOLANA_RPC_URL>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "bagos": {
      "command": "npx",
      "args": [
        "-y",
        "bagos-mcp-server"
      ],
      "env": {
        "BAGS_API_KEY": "<YOUR_BAGS_API_KEY>",
        "SOLANA_RPC_URL": "<YOUR_SOLANA_RPC_URL>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add bagos --env 'BAGS_API_KEY=<YOUR_BAGS_API_KEY>' --env 'SOLANA_RPC_URL=<YOUR_SOLANA_RPC_URL>' -- npx -y bagos-mcp-server
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.bagos]
command = "npx"
args = ["-y", "bagos-mcp-server"]

[mcp_servers.bagos.env]
BAGS_API_KEY = "<YOUR_BAGS_API_KEY>"
SOLANA_RPC_URL = "<YOUR_SOLANA_RPC_URL>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'BAGS_API_KEY=<YOUR_BAGS_API_KEY>' -e 'SOLANA_RPC_URL=<YOUR_SOLANA_RPC_URL>' bagos npx -- -y bagos-mcp-server
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "bagos": {
      "command": "npx",
      "args": [
        "-y",
        "bagos-mcp-server"
      ],
      "env": {
        "BAGS_API_KEY": "<YOUR_BAGS_API_KEY>",
        "SOLANA_RPC_URL": "<YOUR_SOLANA_RPC_URL>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `BAGS_API_KEY` | yes | yes | Bags API key from dev.bags.fm. Required for all tools. |
| `SOLANA_RPC_URL` | no | yes | Custom Solana RPC endpoint. Defaults to the public RPC for BAGS_NETWORK. |
| `BAGS_ALLOW_UNCAPPED_TOKEN_SWAPS` | no | no | Permit non-SOL-input swaps, which the SOL-denominated caps cannot limit. |
| `BAGS_ALLOW_UNCONFIRMED` | no | no | Set true to skip the two-step confirmation on writes. Default false. |
| `BAGS_KEYPAIR_PATH` | no | no | Path to a Solana keypair JSON file. Only required for write tools. |
| `BAGS_MAX_SOL_PER_SESSION` | no | no | Hard cap on total SOL spent across one server session. Default 1.0. |
| `BAGS_MAX_SOL_PER_TX` | no | no | Hard cap on SOL spent by any single transaction. Default 0.1. |
| `BAGS_NETWORK` | no | no | Solana cluster: devnet (default) or mainnet. Writes on mainnet move real funds. |
| `BOS_REQUIRED_BALANCE` | no | no | Minimum BOS balance required to call write tools. Default 10000. |
| `BOS_TOKEN_MINT` | no | no | Mint address of the BOS token used for gating write tools. |
| `USE_MOCK_DATA` | no | no | Makes bags_get_claimable_fees return fabricated data instead of calling the API. Default false. |

## Tools (14)

- `bags_authenticate`: Authenticate with Bags API utilizing the V2 signature challenge flow. Uses the wallet at BAGS_KEYPAIR_PATH (default ~/.config/bags/keypair.json).
- `bags_claim_fees`: GATED WRITE: Claim pending creator/LP fees for the given token mints. Requires $BOS. Two-step: the first call previews and returns a confirmation token; call again with it to sign and submit. Returns confirmed on-chain signatures.
- `bags_execute_trade`: GATED WRITE: Swap tokens on Bags pools. Requires $BOS. Two-step: the first call returns a preview and a confirmation token; call again with that token to sign and submit. Returns a confirmed on-chain signature. SOL mint: So11111111111111111111111111111111111111112.
- `bags_get_claimable_fees`: Query all claimable creator/LP fees for a wallet. Free read-only tier.
- `bags_get_creators`: Query top creators by lifetime fees on Bags. Free read-only tier.
- `bags_get_partner_stats`: View partner referral earnings for the configured wallet. Free read-only tier.
- `bags_get_token_analytics`: Get pool info, claim stats, and bonding curve progress for a token. Free read-only tier.
- `bags_get_token_claim_events`: Get the fee-claim audit trail for a token: who claimed, how much, when, and the transaction signature. Paginated via limit/offset. Free read-only tier.
- `bags_get_token_claim_stats`: Get per-creator claim totals for a token: each fee-share creator with their royalty split and total claimed amount. Free read-only tier.
- `bags_get_token_creators`: Get the royalty split for a token: every creator sharing its fees, their wallet, social provider, and share in basis points. Free read-only tier.
- `bags_get_trade_quote`: Get a swap quote to trade SOL and any Bags ecosystem token. Free read-only tier. SOL mint: So11111111111111111111111111111111111111112. Default BOS token mint: EkJuyYyD3to61CHVPJn6wHb7xANxvqApnVJ4o2SdBAGS.
- `bags_heartbeat`: Periodic health check combining basic node status with an earnings/balance summary. Free read-only tier.
- `bags_prepare_token_metadata`: GATED: Create token info and metadata on Bags, returning the reserved mint address and metadata URL. Requires $BOS. This PREPARES a launch — it does not launch the token and does not send an on-chain transaction.
- `bags_resolve_launch_wallet`: Resolve a social handle (twitter, tiktok, kick, or github) to its Bags fee-share launch wallet. Free read-only tier.

## FAQ

### How do I prevent the AI from spending too much money?

The server enforces default spend caps of 0.1 SOL per transaction and 1 SOL per session, which are refused before the Bags SDK is even called.

### Can the AI trade tokens other than SOL?

By default, swaps involving tokens other than SOL are refused because they cannot be valued in SOL for the spend caps. You must set BAGS_ALLOW_UNCAPPED_TOKEN_SWAPS=true to permit them.
