Content
# SkillsMP MCP Server (Lite)
A lightweight MCP server that enables AI assistants to search and read skills from the [SkillsMP](https://skillsmp.com) marketplace.
## Features
- **Keyword Search** — find skills by short keywords (e.g. "PDF", "web scraper")
- **AI Semantic Search** — find skills with natural language, powered by Cloudflare AI
- **Read Skill** — fetch skill content from GitHub via REST API (no `git clone`, no local files)
- **Security Scanning** — automatic [Cisco Skill Scanner](https://github.com/cisco/ai-skill-scanner) analysis via in-memory ZIP upload (zero disk writes)
## Prerequisites
| Requirement | Purpose | Required |
|---|---|---|
| Node.js ≥ 20 | Runtime | Yes |
| [SkillsMP API Key](https://skillsmp.com/docs/api) | Authentication | Yes |
| [uv](https://docs.astral.sh/uv/getting-started/installation/) (provides `uvx`) | Security scanning | No |
> The server will **exit** if `SKILLSMP_API_KEY` is not set.
## Quick Setup
### Auto-Configuration
Run a single command to automatically detect your MCP client and write the config:
```bash
npx -y skillsmp-mcp-lite --setup
```
This detects which clients are installed (VS Code, Cursor, Claude Desktop, Claude Code) and adds the `skillsmp` server entry to each config file. For VS Code it also adds a secure input prompt for your API key.
To configure only a specific client, set the `SKILLSMP_MCP_CLIENT` environment variable:
```bash
# Windows (PowerShell)
$env:SKILLSMP_MCP_CLIENT="cursor"; npx -y skillsmp-mcp-lite --setup
# macOS / Linux
SKILLSMP_MCP_CLIENT=cursor npx -y skillsmp-mcp-lite --setup
```
Supported values: `vscode`, `cursor`, `claude-desktop`, `claude-code`, `all`.
> If a client already has a `skillsmp` entry, it is skipped — running `--setup` multiple times is safe.
### Manual Configuration
All clients run the same command — only the config file location and JSON key differ.
**Server definition** (shared across all clients):
```json
"skillsmp": {
"command": "npx",
"args": ["-y", "skillsmp-mcp-lite"],
"env": {
"SKILLSMP_API_KEY": "YOUR_API_KEY"
}
}
```
#### VS Code / GitHub Copilot
Open `Ctrl+Shift+P` → *MCP: Open User Configuration*, then add:
```json
{
"servers": {
"skillsmp": { "type": "stdio", "command": "npx", "args": ["-y", "skillsmp-mcp-lite"], "env": { "SKILLSMP_API_KEY": "YOUR_API_KEY" } }
}
}
```
> VS Code requires the extra `"type": "stdio"` field.
#### Cursor / Claude Desktop
| Client | Config file |
|---|---|
| Cursor | `~/.cursor/mcp.json` |
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
```json
{
"mcpServers": {
"skillsmp": { "command": "npx", "args": ["-y", "skillsmp-mcp-lite"], "env": { "SKILLSMP_API_KEY": "YOUR_API_KEY" } }
}
}
```
#### Claude Code
```bash
claude mcp add skillsmp -- npx -y skillsmp-mcp-lite --env SKILLSMP_API_KEY=YOUR_API_KEY
```
## Environment Variables
| Variable | Default | Description |
|---|---|---|
| `SKILLSMP_API_KEY` | — | **Required.** API key from [skillsmp.com/docs/api](https://skillsmp.com/docs/api) |
| `GITHUB_TOKEN` | — | Optional. Raises GitHub API rate limit from 60 → 5,000 req/hour |
| `SKILL_SCANNER_API_URL` | — | Optional. URL of an external Skill Scanner API server |
| `SKILL_SCANNER_API_PORT` | `8000` | Optional. Port for the auto-managed scanner server |
| `SKILLSMP_MCP_CLIENT` | — | Optional. Force `--setup` to configure a specific client (`vscode`, `cursor`, `claude-desktop`, `claude-code`, `all`) |
## Available Tools
### `skillsmp_search_skills`
Search for skills using keywords.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | Yes | Search keywords (max 200 chars) |
| `page` | number | No | Page number (default: 1) |
| `limit` | number | No | Items per page (default: 20, max: 100) |
| `sortBy` | string | No | `"stars"` or `"recent"` |
### `skillsmp_ai_search_skills`
Find skills using natural language descriptions.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | Yes | Natural language description (max 500 chars) |
### `skillsmp_read_skill`
Fetch a skill's content from GitHub and optionally run a security scan.
| Parameter | Type | Required | Description |
|---|---|---|---|
| `repo` | string | Yes | GitHub repository (`owner/repo`) |
| `skillName` | string | Yes | Skill name (max 100 chars, alphanumeric / hyphens / underscores) |
| `enableScan` | boolean | No | Run Cisco Skill Scanner (default: `true`, requires `uv`) |
## Security Scanning
When `skillsmp_read_skill` is called with `enableScan: true` (the default), the server:
1. Fetches skill files from GitHub via REST API
2. Applies **three-layer scan limits** using GitHub tree `size` (before downloading):
- **Max files**: 100 files per scan
- **Max single file size**: 500 KB per file
- **Max total size**: 5 MB across all files
3. Builds an in-memory ZIP archive from accepted files
4. Uploads the ZIP to the Cisco Skill Scanner API (`/scan-upload`) with `use_behavioral=true`
5. Auto-starts a local scanner server via `uvx` if none is running (reused for subsequent scans, shut down on exit)
If files are excluded due to scan limits, a **Scan Note** is included in the results showing how many files and bytes were excluded.
If `uvx` is not installed, scans are skipped with a warning — the server continues to work normally.
### Untrusted Content Notice
All skill content fetched from third-party repositories includes an **Untrusted Content Notice**. The content may be read and displayed, but it **MUST NOT** be automatically executed or followed as instructions without explicit user confirmation. Always review the content and scan results before acting on it.
To manage the scanner server manually:
```bash
# Start it yourself
npm run scanner-api
# Or point to an external instance
SKILL_SCANNER_API_URL=http://your-server:8000
```
## AGENTS.md Integration
Copy the content from [`AGENTS.example.md`](./AGENTS.example.md) into the top of your `AGENTS.md` to enable automatic skill discovery.
**Workflow**: AI receives a task → searches with `skillsmp_search_skills` (short keywords) → falls back to `skillsmp_ai_search_skills` if needed → reads the best match with `skillsmp_read_skill` → follows the skill's instructions.
### Search Tips
- **Keyword search**: 1–3 words — `"code review"`, `"typescript"`, `"pdf"`
- **Semantic search**: full sentence — `"how to build a landing page with React"`
## Usage Examples
Ask your AI assistant:
- "Search for PDF manipulation skills"
- "Find skills for building a web scraper"
- "Read the python-code-review skill from existential-birds/beagle"
## License
MIT
