# MCP Server Overview

The `@noelclaw/research` MCP server exposes Noel's tools to any MCP-compatible AI client. Install it once via `npx` — no build step needed — and use Noel's research, market data, signals, whale tracking, and DeFi wallet tools from Claude, Hermes, Cursor, or any other MCP host.

```bash
npx @noelclaw/research
```

***

## Available Tools

### Market & Data

| Tool              | Description                                                      |
| ----------------- | ---------------------------------------------------------------- |
| `get_market_data` | Live top-20 coins by market cap, trending, BTC/ETH/SOL prices    |
| `get_token_data`  | Price, 24h change, market cap, and volume for any specific token |
| `ask_noel`        | Chat with Noel — DeFi AI with live market context                |

### Trading Signals

| Tool                 | Description                                                                       |
| -------------------- | --------------------------------------------------------------------------------- |
| `get_latest_signal`  | Latest BTC and/or ETH 1H trading signals with entry, TP, SL, and confidence score |
| `get_signal_history` | Signal history with win/loss record and winrate stats                             |
| `get_daily_recap`    | Today's trading performance recap with AI review                                  |

### Whale Tracking

| Tool               | Description                                                                 |
| ------------------ | --------------------------------------------------------------------------- |
| `get_whale_alerts` | Recent large wallet movements, CEX inflow/outflow, and smart money patterns |

### Autonomous Research

| Tool                  | Description                                                                  |
| --------------------- | ---------------------------------------------------------------------------- |
| `run_research`        | On-demand research snapshot with confidence scores                           |
| `start_research`      | Start an 8-hour autonomous research shift (Telegram reports at 2.5h, 5h, 8h) |
| `stop_research`       | Stop an active research shift                                                |
| `get_research_status` | Check shift status and view recent reports                                   |
| `get_research_report` | Get the latest research report for a specific token                          |

### DeFi Wallet

| Tool             | Description                                                    |
| ---------------- | -------------------------------------------------------------- |
| `connect_wallet` | Create or retrieve a Base mainnet wallet (Privy Server Wallet) |
| `swap_tokens`    | Swap ETH, USDC, USDT, DAI, WETH on Base via 0x Permit2         |
| `send_token`     | Send ETH or ERC-20 tokens to any address on Base               |
| `get_portfolio`  | Get wallet token balances and total USD value                  |

### Configuration

| Tool                 | Description                                                       |
| -------------------- | ----------------------------------------------------------------- |
| `create_wallet`      | Create a Base wallet for MCP/agent use                            |
| `get_wallet_balance` | Get ETH and USDC balance for a wallet                             |
| `set_telegram`       | Configure personal Telegram bot for receiving results and reports |

***

## How It Works

```
AI Client (Hermes / Claude / Cursor)
    │
    │  MCP protocol (stdio)
    ▼
@noelclaw/research (Node.js process via npx)
    │
    │  HTTPS calls to Convex HTTP router
    ▼
https://valuable-fish-533.convex.site
    │
    ├── /mcp/market              → Market data (Bankr LLM)
    ├── /mcp/chat                → Noel agent chat
    ├── /mcp/token               → Token-specific data
    ├── /mcp/signals/latest      → Latest BTC/ETH signals
    ├── /mcp/signals/history     → Signal history + winrate
    ├── /mcp/signals/recap       → Daily recap
    ├── /mcp/whale-alerts        → Whale movement alerts
    ├── /mcp/research            → On-demand research snapshot
    ├── /mcp/research/start      → Start 8h shift
    ├── /mcp/research/stop       → Stop shift
    ├── /mcp/research/status     → Get shift status
    ├── /mcp/research/report     → Get report by token
    ├── /mcp/defi/connect        → Create/get Privy wallet
    ├── /mcp/defi/swap           → Swap tokens via 0x Permit2
    ├── /mcp/defi/send           → Send ETH or ERC-20
    ├── /mcp/defi/portfolio      → Wallet balances
    ├── /mcp/wallet/create       → Create basic MCP wallet
    ├── /mcp/wallet/balance      → Get wallet balance
    └── /user/telegram           → Save Telegram config
```

The MCP server is a lightweight proxy — it holds no API keys. All secrets live in Convex environment variables on the server side.

***

## Quick Install

### Claude Code

```bash
claude mcp add noelclaw -- npx @noelclaw/research
```

### Claude Desktop

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

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["@noelclaw/research"]
    }
  }
}
```

Restart Claude Desktop. Tools appear automatically.

### Cursor / Windsurf

Open **Settings → MCP** or edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["@noelclaw/research"]
    }
  }
}
```

### Hermes Agent

```bash
hermes mcp add noelclaw --command npx --args @noelclaw/research
```

Or in your Hermes config:

```yaml
mcp_servers:
  noelclaw:
    command: npx
    args:
      - "@noelclaw/research"
```

***

## Custom Deployment

By default the MCP server uses Noelclaw's hosted Convex backend. To point it at your own deployment:

```bash
NOELCLAW_CONVEX_URL="https://your-deployment.convex.site" npx @noelclaw/research
```

Or in your MCP config:

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["@noelclaw/research"],
      "env": {
        "NOELCLAW_CONVEX_URL": "https://your-deployment.convex.site"
      }
    }
  }
}
```

***

## Tool Reference

### `get_market_data`

No inputs required. Returns live prices and rankings for top 20 coins by market cap, trending tokens, and key prices for BTC, ETH, and SOL.

***

### `ask_noel`

| Parameter  | Type   | Required | Description                      |
| ---------- | ------ | -------- | -------------------------------- |
| `question` | string | yes      | Your question or prompt          |
| `userId`   | string | no       | User ID for personalized context |
| `messages` | array  | no       | Prior conversation turns         |

Noel answers with live market context pulled from Bankr's data layer.

***

### `get_token_data`

| Parameter  | Type   | Required | Description                                      |
| ---------- | ------ | -------- | ------------------------------------------------ |
| `question` | string | yes      | Token name or ticker, e.g. "show me ETH and SOL" |

***

### `get_latest_signal`

| Parameter | Type   | Required | Description                        |
| --------- | ------ | -------- | ---------------------------------- |
| `token`   | string | no       | `"BTC"`, `"ETH"`, or omit for both |
| `userId`  | string | no       | User ID for Telegram delivery      |

Returns the latest 1H signal generated at 08:00 UTC for BTC and/or ETH, with entry price, TP1, TP2, stop loss, and confidence score.

***

### `get_signal_history`

| Parameter | Type   | Required | Description                               |
| --------- | ------ | -------- | ----------------------------------------- |
| `token`   | string | no       | Filter by `"BTC"` or `"ETH"`              |
| `limit`   | number | no       | Number of signals to return (default: 10) |

***

### `get_daily_recap`

No required inputs. Returns today's performance summary with win/loss counts, total PnL, and an AI-written review.

***

### `get_whale_alerts`

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `hours`   | number | no       | How far back to look (default: 6) |
| `userId`  | string | no       | User ID for Telegram delivery     |

Returns large on-chain movements, CEX inflow/outflow events, and smart money patterns detected in the specified time window.

***

### `run_research`

| Parameter | Type   | Required | Description                   |
| --------- | ------ | -------- | ----------------------------- |
| `userId`  | string | no       | User ID for Telegram delivery |
| `token`   | string | no       | Focus token for the snapshot  |

Returns a one-off research snapshot with market outlook, key signals, and confidence scores.

***

### `start_research`

| Parameter | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `userId`  | string | yes      | User ID to associate the shift with |
| `token`   | string | no       | Token to focus the shift on         |

Starts an 8-hour autonomous research shift. Noel collects market data every 30 minutes and sends Telegram reports at 2.5h, 5h, and 8h.

***

### `stop_research`

| Parameter | Type   | Required | Description                 |
| --------- | ------ | -------- | --------------------------- |
| `userId`  | string | yes      | User ID of the active shift |

***

### `get_research_status`

| Parameter | Type   | Required | Description      |
| --------- | ------ | -------- | ---------------- |
| `userId`  | string | yes      | User ID to check |

Returns active shift progress (elapsed time, reports sent) and recent report summaries.

***

### `get_research_report`

| Parameter | Type   | Required | Description                        |
| --------- | ------ | -------- | ---------------------------------- |
| `token`   | string | yes      | Token to get the latest report for |

***

### `connect_wallet`

| Parameter | Type   | Required | Description                                |
| --------- | ------ | -------- | ------------------------------------------ |
| `userId`  | string | yes      | User ID to create or retrieve a wallet for |

Creates a Privy Server Wallet on Base mainnet. If the user already has one, returns the existing address. Wallets are non-custodial — the private key is managed by Privy and never exposed.

***

### `swap_tokens`

| Parameter     | Type   | Required | Description                                         |
| ------------- | ------ | -------- | --------------------------------------------------- |
| `userId`      | string | yes      | User ID of the wallet to use                        |
| `fromToken`   | string | yes      | Token to sell: `ETH`, `USDC`, `USDT`, `DAI`, `WETH` |
| `toToken`     | string | yes      | Token to buy                                        |
| `amount`      | string | yes      | Amount in wei (for ETH) or smallest unit            |
| `slippageBps` | number | no       | Slippage tolerance in basis points (default: 100)   |

Routes through 0x Permit2 on Base mainnet. Handles token approval automatically when needed.

***

### `send_token`

| Parameter   | Type   | Required | Description                             |
| ----------- | ------ | -------- | --------------------------------------- |
| `userId`    | string | yes      | User ID of the sending wallet           |
| `toAddress` | string | yes      | Recipient address                       |
| `token`     | string | yes      | `ETH`, `USDC`, `USDT`, `DAI`, or `WETH` |
| `amount`    | string | yes      | Amount in wei or token units            |

***

### `get_portfolio`

| Parameter | Type   | Required | Description           |
| --------- | ------ | -------- | --------------------- |
| `userId`  | string | yes      | User ID of the wallet |

Returns token balances and total USD value for the user's Base mainnet wallet.

***

### `create_wallet`

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| `userId`  | string | yes      | User ID for the wallet |

Creates a basic MCP wallet (stored in Convex). Use `connect_wallet` for Privy Server Wallets with full swap/send support.

***

### `get_wallet_balance`

| Parameter | Type   | Required | Description                  |
| --------- | ------ | -------- | ---------------------------- |
| `userId`  | string | yes      | User ID to check balance for |

Returns ETH and USDC balances.

***

### `set_telegram`

| Parameter          | Type   | Required | Description               |
| ------------------ | ------ | -------- | ------------------------- |
| `userId`           | string | yes      | User ID to configure      |
| `telegramBotToken` | string | no       | Bot token from @BotFather |
| `telegramChatId`   | string | no       | Your Telegram chat ID     |

Configure where Noel sends research reports, signals, and whale alerts.

**How to get your credentials:**

1. Open Telegram → search `@BotFather` → `/newbot`
2. Copy the token
3. Start a chat with your bot → send any message
4. Visit `https://api.telegram.org/bot<TOKEN>/getUpdates`
5. Copy the `chat.id` from the JSON response

***

## Troubleshooting

| Error                         | Fix                                                                    |
| ----------------------------- | ---------------------------------------------------------------------- |
| `BANKR_API_KEY not set`       | Set via `npx convex env set BANKR_API_KEY "..."` in the Convex project |
| `TELEGRAM_BOT_TOKEN not set`  | Set via `npx convex env set TELEGRAM_BOT_TOKEN "..."`                  |
| Tools not appearing           | Restart your MCP client after adding the config                        |
| `Noelclaw API error: 404`     | Wrong `NOELCLAW_CONVEX_URL` or Convex not deployed                     |
| Server starts but no response | Normal — it waits for MCP stdin, not HTTP                              |
| `No wallet found`             | Call `connect_wallet` first to create a wallet for your userId         |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.noelclaw.fun/mcp-skill-reference/mcp-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.