kol-quest MCP server
Commit Nov 11, 2026Enables AI assistants to track smart money wallet moves, monitor KOL leaderboards, and discover new tokens on Solana and BSC in real time.
Also known as nirholas/kol-quest
- Stars
- 29
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 11, 2026
- License
- —
What is kol-quest MCP?
kol-quest enables AI assistants to track smart money wallet moves, monitor KOL leaderboards, and discover new tokens on Solana and BSC in real time. It exposes 6 tools, such as kolscan_leaderboard, kolscan_wallet, gmgn_wallets.
Summary generated from the project's README
About kol-quest MCP server
Kol-quest provides an intelligence layer for tracking smart money movements and influencer activity on the Solana and BSC blockchains. It enables AI assistants to monitor real-time trade feeds, including buy and sell streams with associated profit and loss data. Developers can use this server to access multi-source KOL rankings that aggregate data from KolScan and GMGN, offering views based on daily, weekly, or monthly performance metrics.
The system operates as an MCP server via stdio, allowing local AI clients to interact with the data. It requires a PostgreSQL database for storing dynamic information like trades and user watchlists. Users can authenticate using Solana, Ethereum, or email via Better-Auth. The server integrates data from various sources including KolScan, GMGN API, and X/Twitter to provide a unified view of top traders and emerging token opportunities.
What you can do with it
- 1Monitor smart money tradesAn AI assistant can track live buy and sell streams from high-performing wallets to identify market trends.
- 2Analyze trader performanceA developer can request rankings of top traders based on specific metrics like win rate or total profit.
- 3Discover new tokensThe assistant can scan real-time activity to find new tokens before they experience significant price movement.
- 4Track influencer leaderboardsUsers can query leaderboards across different timeframes to see which KOLs are currently most successful.
Written from the project's README. Every use case is checked against a quote from it.
kol-quest MCP tools 6
Detected from the READMEkolscan_leaderboardkolscan_walletgmgn_walletsgmgn_wallet_detailwallet_statssearch_wallets
| kolscan_leaderboard | — | |
| kolscan_wallet | — | |
| gmgn_wallets | — | |
| gmgn_wallet_detail | — | |
| wallet_stats | — | |
| search_wallets | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenirholas/kol-quest is public and reachablegithub.com/nirholas/kol-quest ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-11github.com/nirholas/kol-quest ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubTrack the best traders. Monitor smart money moves in real time. Discover new tokens before they run.
Live: kol.quest · Docs: docs.kol.quest
Features
Multi-source KOL rankings across daily, weekly, and monthly timeframes. KolScan profit leaders, GMGN smart money wallets, win rate filters, and a unified All Solana view that merges every data source.
Live trade feeds from smart money wallets as they happen. Token discovery, wallet monitoring, buy/sell streams with P&L — three real-time views for different tracking styles.
Community-driven wallet discovery. Submit wallets, vouch for others' finds, and browse approved submissions. Full moderation workflow with admin controls.
Sign in with your wallet. Solana (ed25519), Ethereum (EIP-191/SIWE), or traditional email — all powered by Better-Auth with role-based access control.
Architecture
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ ┌──────────────────┐
│ DATA SOURCES │ │ INGESTION │ │ STORAGE │ │ APPLICATION │
│ │ │ │ │ │ │ │
│ KolScan.io │────>│ scrape.js │────>│ JSON files │────>│ Next.js 14 │
│ GMGN API │────>│ scrape-axiom.js │ │ (leaderboard, │ │ (React 18, TS) │
│ X / Twitter │────>│ scrape-x.js │ │ wallets, X) │ │ │
│ │ │ │ │ │ │ Leaderboards │
│ │ │ ingest-trades │────>│ PostgreSQL │────>│ Tracking │
│ │ │ (batch + poll) │ │ (trades, │ │ Feed │
│ │ │ │ │ submissions, │ │ Community │
│ │ │ │ │ watchlists, │ │ Auth │
│ │ │ │ │ users) │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘ └──────────────────┘
│
│
┌──────────────────────┴──────────┐
│ │
┌─────┴──────┐ ┌─────────┴──────┐
│ Bun API │ │ MCP Server │
│ :3002 │ │ (stdio) │
│ REST/JSON │ │ AI assistants │
└────────────┘ └────────────────┘
Data Flow
Static Data (JSON files) — Scrapers run on-demand, writing JSON to disk. The Next.js app reads these files at request time. If local files are missing, it falls back to GitHub raw URLs so the app works without running scrapers.
Dynamic Data (PostgreSQL) — Trade ingestion writes trade records to the database. User data (accounts, sessions, watchlists, submissions) lives entirely in PostgreSQL via Drizzle ORM.
Merge Strategy — The All Solana view merges KolScan + GMGN data into a unified UnifiedWallet format, deduplicated by wallet address with GMGN data taking priority.
Tech Stack
| Layer | Technology |
|---|---|
| Framework | Next.js 14, React 18, TypeScript |
| Styling | Tailwind CSS, custom dark design system |
| Database | PostgreSQL + Drizzle ORM |
| Auth | Better-Auth — email, Solana, Ethereum |
| Scraping | Playwright, xactions (X/Twitter) |
| Crypto | TweetNaCl, bs58, ethers.js |
| Data | KolScan API, GMGN API, X/Twitter |
| API | Next.js API Routes + Bun REST API (port 3002) |
| AI Integration | MCP Server (Model Context Protocol) |
Getting Started
Prerequisites
- Node.js 18+
- PostgreSQL (local or hosted — Neon, Supabase, Railway all work)
- Chromium (for scrapers — installed via Playwright)
- Bun (optional, for the standalone API and MCP servers)
Install
# Clone the repo
git clone https://github.com/nirholas/kol-quest.git
cd kol-quest
# Root dependencies (scrapers)
npm install
# Site dependencies (Next.js app)
cd site && npm install && cd ..
# Playwright for scraping
npx playwright install chromium
sudo npx playwright install-deps chromium # Linux only
Or use the setup script:
npm run setup
Configure
cp site/.env.example site/.env
| Variable | Required | Description |
|---|---|---|
DATABASE_URL |
Yes | PostgreSQL connection string: postgres://user:pass@host:5432/dbname |
AUTH_SECRET |
Yes | Random secret for session signing. Generate with openssl rand -hex 32 |
NEXT_PUBLIC_URL |
Recommended | Your app's public URL. Default: http://localhost:3000 |
NEXT_PUBLIC_BETTER_AUTH_URL |
Recommended | Auth URL (usually same as above) |
ADMIN_USERNAME |
Optional | Username that auto-promotes to admin on first login |
GMGN_TOKEN |
Optional | Bearer token for GMGN API (used by trade polling) |
Database Setup
cd site
npm run db:push # Push schema directly (development)
npm run db:generate # Generate migration SQL from schema changes
npm run db:migrate # Apply pending migrations (production)
This creates all tables: user, session, account, verification, wallet_submission, wallet_vouch, wallet_address, trade, watchlist.
Scrape Data
Before the app has anything to display, scrape the data sources:
npm run scrape # KolScan KOL leaderboard (~472 wallets)
npm run scrape:axiom # GMGN smart money wallets (Solana + BSC)
npm run scrape:x # X/Twitter profiles for KOL social data
Copy fresh data to the Next.js app:
cp output/kolscan-leaderboard.json site/data/
cp solwallets.json site/data/
cp bscwallets.json site/data/
Note: If local files are missing, the app falls back to GitHub raw URLs — so you can skip scraping entirely and use the last committed data.
Run
# Development
npm run dev
# Production
cd site && npm run build && npm start
Open http://localhost:3000.
First Admin User
- Sign up with the username matching
ADMIN_USERNAMEin your.env - The bootstrap endpoint auto-promotes that user to admin
- Admin can approve/reject community wallet submissions at
/admin/submissions
API Reference
KolQuest exposes two API surfaces for programmatic access.
Next.js API Routes
Base URL: your app URL (e.g. http://localhost:3000)
Trades — GET /api/trades
Query trade activity with cursor-based pagination. No auth required.
| Param | Type | Description | Default |
|---|---|---|---|
chain |
string | "sol", "bsc", or omit for all |
all |
wallet |
string | Filter by wallet address | — |
type |
string | "buy" or "sell" |
all |
limit |
number | 1–200 | 50 |
cursor |
string | ISO timestamp for pagination | — |
# Recent trades
curl 'http://localhost:3000/api/trades?limit=10'
# Solana buys only
curl 'http://localhost:3000/api/trades?chain=sol&type=buy'
# Specific wallet with pagination
curl 'http://localhost:3000/api/trades?wallet=CyaE1Vxv...&cursor=2025-01-15T12:30:00.000Z'
{
"trades": [
{
"id": "...",
"walletAddress": "...",
"walletLabel": "DegenKing",
"walletTags": "[\"kol\",\"smart_degen\"]",
"chain": "sol",
"type": "buy",
"tokenAddress": "...",
"tokenSymbol": "BONK",
"tokenName": "Bonk",
"tokenLogo": "https://...",
"amountUsd": 12420.50,
"amountToken": 50000000,
"priceUsd": 0.000248,
"realizedProfit": 3200.00,
"realizedProfitPnl": 0.35,
"txHash": "...",
"source": "gmgn",
"tradedAt": "2025-01-15T12:30:00.000Z"
}
],
"nextCursor": "2025-01-15T12:29:00.000Z"
}
Submissions — GET /api/submissions
List all approved community wallet submissions. No auth required.
Submissions — POST /api/submissions
Submit a new wallet for community review. Auth required, rate limited to 12/hour per user.
| Field | Required | Validation |
|---|---|---|
walletAddress |
Yes | Trimmed string |
chain |
Yes | "solana" or "bsc" |
label |
Yes | 2–80 characters |
notes |
No | Max 800 characters |
twitter |
No | HTTPS URL |
telegram |
No | HTTPS URL |
Watchlist — GET /api/watchlist
Get the authenticated user's watchlisted wallets. Auth required.
Watchlist — POST /api/watchlist
Add a wallet to the watchlist. Auth required.
Watchlist — PATCH /api/watchlist
Update label or group for a watchlisted wallet. Auth required.
Watchlist — DELETE /api/watchlist
Remove a wallet from the watchlist. Auth required.
Admin — GET /api/submissions/pending
List pending submissions. Admin only.
Admin — POST /api/submissions/[id]/approve | POST /api/submissions/[id]/reject
Approve or reject a pending submission. Admin only.
Bun REST API (Standalone)
A lightweight read-only REST API server powered by Bun, running independently on port 3002. Ideal for integrations, bots, and external tools that need fast access to wallet data without the full Next.js app.
bun api/index.ts
# or
npm run api
GET /health
Health check returning data counts and server status.
GET /kolscan/leaderboard
KolScan KOL leaderboard with sorting, filtering, and search.
| Param | Type | Description | Default |
|---|---|---|---|
timeframe |
number | 1 (daily), 7 (weekly), 30 (monthly) |
1 |
sort |
string | profit, wins, losses, winrate, name |
profit |
order |
string | asc or desc |
desc |
limit |
number | 1–100 | 20 |
search |
string | Search by name or address | — |
GET /kolscan/wallet/:address
Detailed data for a specific KolScan wallet across all timeframes.
GET /gmgn/wallets
GMGN smart money wallets for Solana or BSC with category filtering.
| Param | Type | Description | Default |
|---|---|---|---|
chain |
string | sol or bsc |
sol |
category |
string | smart_degen, kol, snipe_bot, launchpad_smart, fresh_wallet |
— |
sort |
string | realized_profit_7d, realized_profit_1d, realized_profit_30d, winrate_7d, buy_7d |
realized_profit_7d |
order |
string | asc or desc |
desc |
limit |
number | 1–100 | 20 |
search |
string | Search by name, address, or Twitter | — |
GET /gmgn/wallet/:address
Complete GMGN data for a specific wallet including PnL breakdowns.
GET /search
Search across all data sources simultaneously (KolScan + GMGN SOL + GMGN BSC).
| Param | Type | Description | Default |
|---|---|---|---|
q |
string | Search term (required) | — |
limit |
number | 1–100 | 20 |
GET /stats
Aggregate statistics across all data sources — wallet counts, category breakdowns, totals.
MCP Server (AI Integration)
KolQuest includes a Model Context Protocol server that exposes wallet intelligence to AI assistants like Claude, GitHub Copilot, Cursor, and any MCP-compatible client.
bun mcp/index.ts
# or
npm run mcp
The server communicates over JSON-RPC via stdio (newline-delimited JSON on stdin/stdout).
Claude Desktop Configuration
Add to ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"kolquest": {
"command": "bun",
"args": ["mcp/index.ts"],
"cwd": "/path/to/kol-quest"
}
}
}
Available Tools
| Tool | Description |
|---|---|
kolscan_leaderboard |
Get KolScan KOL leaderboard ranked by profit, win rate, or other metrics. Supports timeframe, sort, order, limit, and search params. |
kolscan_wallet |
Get detailed data for a specific KolScan wallet — total profit, wins, losses, win rate, per-timeframe breakdowns, external links. |
gmgn_wallets |
Get GMGN smart money wallets for Solana or BSC. Filter by category (smart_degen, kol, snipe_bot, etc.), sort by profit or win rate. |
gmgn_wallet_detail |
Get complete GMGN data for a specific wallet — chain, category, tags, balance, PnL by timeframe, buy/sell counts, win rates. |
wallet_stats |
Aggregate statistics across all data sources — total wallet counts, category breakdowns, combined totals. |
search_wallets |
Search across all data sources simultaneously (KolScan + GMGN SOL + GMGN BSC) by name, address, or Twitter handle. |
Example Prompts
With the MCP server connected, you can ask an AI assistant things like:
- "Who are the top 5 most profitable KOLs today?"
- "Look up wallet CyaE1Vxv... — what's their win rate?"
- "Show me GMGN smart degen wallets on Solana sorted by 7d profit"
- "Search for any wallets associated with @CryptoWhale on Twitter"
- "Give me overall stats across all data sources"
Authentication
KolQuest supports three sign-in methods via Better-Auth:
| Method | Plugin | How It Works |
|---|---|---|
| Email / Password | username() |
Standard username (3–20 chars) + password (8+ chars) |
| Solana Wallet | Custom solanaWallet() |
ed25519 signature verification via TweetNaCl. Nonce-based challenge-response with 5-minute expiry. |
| Ethereum Wallet | siwe() |
EIP-191 / SIWE signature verification via ethers.js. MetaMask-compatible. |
All three methods create the same session/user records — the rest of the app doesn't care how the user authenticated.
Roles: user (default) and admin. The first user matching ADMIN_USERNAME is auto-promoted.
Database Schema
PostgreSQL with Drizzle ORM. Schema defined in site/drizzle/db/schema.ts.
| Table | Purpose |
|---|---|
user |
Core user accounts (id, name, email, role, username) |
session |
Active sessions with expiry, IP, user agent |
account |
Linked auth providers (credential, siwe, solana-wallet) |
verification |
Email verification tokens |
wallet_submission |
Community-submitted wallets with moderation status |
wallet_vouch |
Community votes on submissions (one per user per submission) |
wallet_address |
User-linked wallet addresses |
trade |
Trade activity records from smart wallets (buy/sell, PnL, token data) |
watchlist |
User-saved wallet watchlist with custom labels and groups |
All foreign keys cascade on delete — removing a user cleans up all their data.
Scrapers
Playwright-based scrapers collect data from three external sources. All scrapers live in the project root.
| Scraper | Command | Source | Output |
|---|---|---|---|
scrape.js |
npm run scrape |
KolScan leaderboard | output/kolscan-leaderboard.json (~472 wallets, 3 timeframes) |
scrape-axiom.js |
npm run scrape:axiom |
GMGN / Axiom smart wallets | output/axiom-smart-wallets.json |
scrape-x-profiles.js |
npm run scrape:x |
X/Twitter profiles | site/data/x-profiles.json (8 concurrent workers, 7-day cache, resumable) |
scrape-gmgn-x-tracker.js |
npm run scrape:x-tracker |
GMGN X tracker accounts | site/data/gmgn-x-tracker.json |
Trade Ingestion
Trade data is ingested into PostgreSQL via site/scripts/ingest-trades.ts:
cd site
npm run ingest # Batch import from JSON wallet files
npm run ingest:poll # Poll GMGN API for recent trade activity
Batch import reads solwallets.json / bscwallets.json and creates trade records from wallet holdings. Live polling hits the GMGN API for each wallet's recent activities (10 wallets in parallel, 2s delay between batches). Both modes use onConflictDoNothing for safe re-runs.
For continuous data, set up polling as a cron job:
*/15 * * * * cd /path/to/kol-quest/site && npx tsx scripts/ingest-trades.ts poll >> /var/log/kolquest-trades.log 2>&1
Pages & Features
Public
| Route | Description |
|---|---|
/ |
Landing page with stats overview and top wallets from each source |
/leaderboard |
KolScan KOL rankings — sortable, searchable, exportable (CSV/JSON). Daily/Weekly/Monthly tabs |
/top-performers |
KolScan leaderboard pre-sorted by win rate |
/most-profitable |
KolScan leaderboard pre-sorted by profit |
/gmgn-sol |
GMGN Solana smart money wallets with category badges and PnL breakdowns |
/bsc |
GMGN BSC wallets — same layout as Solana |
/all-solana |
Unified leaderboard merging KolScan + GMGN (~1,300+ unique wallets) |
/wallet/[address] |
KolScan wallet detail — stats, rankings, X profile, PnL calendar, sparklines |
/gmgn-wallet/[address] |
GMGN wallet detail — PnL by timeframe, trading stats, distribution chart |
/community |
Approved community-submitted wallets |
/calendar |
PnL calendar heatmap across all tracked wallets |
/docs |
API Playground, REST API reference, MCP setup guide |
Authenticated
| Route | Description |
|---|---|
/track |
Real-time token discovery — new tokens being traded by smart wallets |
/monitor |
Live activity feed from smart money wallets |
/tracker |
Personal wallet watchlist with custom groups |
/feed |
Real-time trade stream with auto-refresh (15s polling, cursor-based infinite scroll) |
/submit |
Wallet submission form (rate-limited to 12/hour) |
/admin/submissions |
Admin-only moderation panel for pending submissions |
Project Structure
kol-quest/
├── api/
│ └── index.ts # Bun REST API server (port 3002)
├── mcp/
│ └── index.ts # MCP server for AI assistants
├── scrape.js # KolScan leaderboard scraper
├── scrape-axiom.js # GMGN/Axiom smart wallet scraper
├── scrape-x-profiles.js # X/Twitter profile scraper
├── scrape-gmgn-x-tracker.js # GMGN X tracker accounts scraper
├── solwallets.json # GMGN Solana wallet data
├── bscwallets.json # GMGN BSC wallet data
├── output/ # Scraper output directory
├── docs/ # Extended documentation
│ ├── api-reference.md # Full API reference
│ ├── architecture.md # System design & data flow
│ ├── authentication.md # Auth flows & session management
│ ├── database.md # Schema, tables, indexes
│ ├── deployment.md # Production hosting guide
│ ├── deploy-cloudflare.md # Live kol.quest hosting (Cloud Run + Cloudflare)
│ ├── features.md # Every page and feature
│ ├── mcp-server.md # MCP server setup & tools
│ ├── scrapers.md # Scraper details & output formats
│ └── trade-ingestion.md # Batch import & live polling
└── site/ # Next.js application
├── app/
│ ├── layout.tsx # Root layout, nav, footer
│ ├── page.tsx # Homepage
│ ├── api/ # Next.js API routes
│ │ ├── auth/ # Better-Auth catch-all
│ │ ├── submissions/ # CRUD + moderation
│ │ ├── trades/ # Trade queries + ingestion
│ │ ├── watchlist/ # User watchlist CRUD
│ │ └── admin/ # Admin bootstrap
│ └── components/ # Shared UI components
├── drizzle/
│ └── db/
│ ├── schema.ts # Database table definitions
│ └── index.ts # DB connection
├── lib/
│ ├── auth.ts # Better-Auth configuration
│ ├── auth-client.ts # Client-side auth hooks
│ ├── data.ts # Data loading (JSON + GitHub fallback)
│ ├── types.ts # TypeScript interfaces
│ ├── solana-auth-plugin.ts # Custom Solana wallet auth
│ └── rate-limit.ts # In-memory rate limiter
├── scripts/
│ └── ingest-trades.ts # Trade data import/poll
└── data/ # Local data files (JSON)
Scripts
| Command | Description |
|---|---|
npm run scrape |
Scrape KolScan leaderboard |
npm run scrape:axiom |
Pull GMGN smart money data |
npm run scrape:x |
Scrape X/Twitter KOL profiles |
npm run scrape:x-tracker |
Scrape GMGN X tracker accounts |
npm run dev |
Start Next.js dev server |
npm run build |
Build for production |
npm run api |
Start standalone Bun REST API on port 3002 |
npm run mcp |
Start MCP server for AI assistants |
npm run setup |
Install all dependencies + Playwright |
cd site && npm run ingest |
Bulk import trades from JSON |
cd site && npm run ingest:poll |
Poll GMGN API for live trades |
cd site && npm run db:push |
Push schema to database |
cd site && npm run db:generate |
Generate migration SQL |
cd site && npm run db:migrate |
Apply pending migrations |
Deployment
Production (Cloud Run + Cloudflare)
kol.quest runs the site/ app on Google Cloud Run, fronted by the Cloudflare Worker in deploy/cloudflare-proxy/. docs.kol.quest is the docs/ folder on Cloudflare Pages. Cloud Scheduler calls /api/cron/analytics-refresh every 15 minutes. Redeploy commands, secrets, and rollback steps are in docs/deploy-cloudflare.md.
kol-quest MCP questions
What tools does kol-quest MCP provide?
It exposes 6 tools, including kolscan_leaderboard, kolscan_wallet, gmgn_wallets, gmgn_wallet_detail, wallet_stats.
Can I use the data for my own bots or tools?
Yes, there is a lightweight Bun-powered REST API designed for integrations, bots, and external tools.
How can I track real-time trades?
The system provides live trade feeds from smart money wallets, including buy/sell streams with P&L.