# Wikicious MCP Server

Connect any MCP-compatible AI assistant (Claude Desktop, Claude Code, Cursor,
VS Code Copilot, Windsurf, Kiro) directly to the Wikicious V6 protocol on
Arbitrum One.

## What it does

Once installed, you can ask Claude (or any MCP client):

- *"What are all the active perp markets on Wikicious and their current prices?"*
- *"Show me all open positions for wallet 0x..."*
- *"What's the funding rate on ETH/USD?"*
- *"What's the current staking APY and my veWIK balance?"*
- *"Open a 5x LONG on ETH/USD with $200 collateral, stop at $2900, TP at $3200"*
- *"Analyze my full Wikicious portfolio for wallet 0x..."*
- *"What's the protocol's monthly revenue?"*

## Tools available

### Read-only (no private key needed)

| Tool | Description |
|---|---|
| `wikicious_get_markets` | All active perp markets + mark prices |
| `wikicious_get_price` | Oracle price for any market |
| `wikicious_get_vault_balance` | USDC vault balance for a wallet |
| `wikicious_get_positions` | All open perp positions for a wallet |
| `wikicious_get_position` | Specific position with on-chain PnL |
| `wikicious_get_funding_rate` | Funding rate + OI imbalance |
| `wikicious_get_lending_rates` | Supply/borrow APY for lending markets |
| `wikicious_get_lending_position` | User's lending position |
| `wikicious_get_staking_info` | Staking lock, veWIK, claimable fees |
| `wikicious_get_amm_stats` | WikiAMM AUM + WLP price |
| `wikicious_get_wik_balance` | WIK token balance |
| `wikicious_get_revenue_stats` | Protocol monthly fees + revenue split |
| `wikicious_get_protocol_summary` | Full protocol health snapshot |

### Write (requires WALLET_PRIVATE_KEY in .env)

| Tool | Description |
|---|---|
| `wikicious_open_position` | Open perp position with TP/SL |
| `wikicious_close_position` | Close an open position |
| `wikicious_deposit_vault` | Deposit USDC into WikiVault |
| `wikicious_withdraw_vault` | Withdraw USDC from WikiVault |
| `wikicious_stake_wik` | Stake WIK with lock duration |
| `wikicious_claim_staking_fees` | Claim USDC fee rewards |

## Setup

### 1. Install

```bash
pip install -r requirements.txt
cp .env.example .env
# Edit .env: add your ARBITRUM_RPC_URL (and WALLET_PRIVATE_KEY for write tools)
```

For faster RPC (recommended):
```
ARBITRUM_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY
```

### 2. Test it works

```bash
python server.py stdio
# In a separate terminal:
npx @modelcontextprotocol/inspector python server.py stdio
```

### 3. Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "wikicious": {
      "command": "python",
      "args": ["/absolute/path/to/wikicious_mcp/server.py", "stdio"],
      "env": {
        "ARBITRUM_RPC_URL": "https://arb1.arbitrum.io/rpc",
        "WALLET_PRIVATE_KEY": "optional_for_write_tools"
      }
    }
  }
}
```

Restart Claude Desktop. You'll see "wikicious" appear in the tools list.

### 4. Add to Claude Code

```bash
claude mcp add wikicious python /absolute/path/to/wikicious_mcp/server.py stdio
```

### 5. Add to Cursor / VS Code / Windsurf

Add to your MCP settings file (varies by IDE):
```json
{
  "wikicious": {
    "command": "python",
    "args": ["/absolute/path/to/wikicious_mcp/server.py", "stdio"]
  }
}
```

## Security

- Read-only tools require no private key — safe to use with any wallet address
- Write tools require `WALLET_PRIVATE_KEY` — use a dedicated trading wallet,
  not your main treasury
- The MCP server runs locally on your machine — no private key leaves your computer
- Never commit `.env` to git

## Contract addresses (Arbitrum One mainnet)

| Contract | Address |
|---|---|
| WikiPerp | `0x723f653a3DEFC45FB934BBF81f1411883a977468` |
| WikiVault | `0x4533E181FdF5b0C66e0816992F38c23d57e42Df8` |
| WikiOracle | `0xA99583D3cd272F95b8f08b32297f072f5164D0DC` |
| WikiStaking | `0xDD551D705fAbD4380D2C95F7345b671cE3310bd2` |
| WikiAMM | `0x5e73fa11c2Fa157dbE59E7B8F7f1b3101c5c6004` |
| WikiLending | `0x74635CFa33EEAe220367fF10C598e098a29e9246` |
| WIK Token | `0xa681Bf6f0449ABc4E98DCa3468488Fe1b24FdD0F` |