Manual
KOLens Cowork plugin & agent skills — creator research inside Claude
Last updated: 2026-06-10
In short
The KOLens plugin packages three things for Claude Cowork: a stdio MCP server (kolens_mcp) that calls the hosted KOLens API with your key, a kol-research skill that teaches Claude the full SMM research workflow — search, vet, build lists, draft outreach — and a /kol-search command for one-step keyword lookups. Install is two environment variables (KOLENS_API_URL, KOLENS_API_KEY) plus the plugin file; after that you work in plain language, Chinese or English: “找 50 个有邮箱的护肤达人” just works.
What's in the plugin
| Component | Name | Purpose |
|---|---|---|
| Skill | kol-research | Teaches Claude the research workflows: fresh keyword search, database queries, single-account lookups, outreach-list prep — with the right tool order and billing awareness |
| Command | /kol-search | One-step keyword → creators flow for quick lookups |
| MCP server | kolens_mcp | Stdio MCP that calls the deployed KOLens API with your key — a workflow-friendly subset of the hosted server's 26 tools |
The skill is what makes the difference: instead of Claude guessing which tool to call, kol-research encodes the proven workflows — when to scrape fresh versus query the existing database, how to poll jobs, when a lookup costs credits — so conversations stay short and spend stays intentional. Trigger phrases work in both languages (“find KOLs for…”, “查找KOL”, “找达人”, “导出达人数据”).
Install in 3 steps
- Get an API key: sign in at kolens.ai and create one under Account → API keys.
- Set two environment variables where Cowork picks them up:
- Add the plugin in Cowork's plugin panel (drag the kolens.plugin file in, or use the plugin-install flow), then start a conversation.
export KOLENS_API_URL="https://kolens.ai"
export KOLENS_API_KEY="kol_xxxxxxxxxxxx"What a session looks like
- “Find 5 fitness TikTok KOLs with over 100k followers that have emails” — quick database query, results with stats and contacts in chat.
- “搜一下 skincare 关键词，抓 100 条视频，筛出互动率 4% 以上、有邮箱的，整理成表” — a fresh scrape (credits confirmed first), then filtered results.
- “Look up @handle — is this account worth $800 a video?” — single-handle lookup plus the dossier-based judgement.
- /kol-search peptides — the command shortcut when you don't need a conversation.
Plugin vs hosted MCP vs REST — which to use
| Surface | Best for | Auth |
|---|---|---|
| Cowork plugin (this page) | Cowork desktop teams who want skills + commands bundled | API key via env vars |
| Hosted MCP (kolens.ai/mcp) | Claude.ai & Claude Code — zero install, OAuth consent | OAuth 2.1 (or API key) |
| REST API | Custom software, backends, scheduled pipelines | Bearer key |
Tip
All three surfaces share one account, one credit balance and one database — work started in Cowork continues seamlessly in the web app and vice versa.
Advanced usage
- Self-hosted API: point KOLENS_API_URL at your own deployment — the plugin is just a client.
- Budget discipline in team settings: issue each teammate their own labeled API key, so plugin usage shows up attributed in usage reports.
- Combine with workspace scope: plugin queries respect personal/team scope like every other client — agency members see their client workspace's data.
Frequently asked questions
Does the plugin cost extra?
No — it bills the same credits as every other surface: scrapes are metered (1 credit ≈ 10 results), reads are free. The plugin itself is free to install.
I use Claude.ai, not Cowork — do I need this?
No — Claude.ai users should add the hosted connector (https://kolens.ai/mcp) via Settings → Connectors instead; it needs no installation at all. See the MCP guide.
Can Claude spend credits without asking?
The kol-research skill instructs Claude to state the credit cost before launching scrapes, and the API pre-charge/refund mechanics cap worst-case spend at what you explicitly approve.
Does it work in Chinese?
Yes — the skill's trigger phrases and workflows are bilingual by design (查找KOL / 找达人 / 导出达人数据), and Douyin searches take Chinese keywords natively.
Related
Ready to try it on real data?
Everything in this manual works on a free account — the homepage demo search doesn't even need one. Your first search takes about 5 minutes.
Get started