# SkillFlow MCP Server

[![npm version](https://img.shields.io/npm/v/skillflow-mcp-server.svg)](https://www.npmjs.com/package/skillflow-mcp-server)
[![npm downloads](https://img.shields.io/npm/dm/skillflow-mcp-server.svg)](https://www.npmjs.com/package/skillflow-mcp-server)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-Published-green)](https://registry.modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Available on SkillFlow](https://raw.githubusercontent.com/rafsilva85/awesome-ai-skills/main/badges/skillflow-available.svg)](https://skillflow.builders)

> Connect AI coding agents to the SkillFlow AI skills marketplace. Live data. Zero config. One command.

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects AI coding agents to the [SkillFlow](https://skillflow.builders) marketplace — a curated AI skills marketplace with trust metrics and performance data.

## Why SkillFlow?

AI agents are the new users. Instead of browsing a website, agents can now **programmatically search, discover, and evaluate skills** from SkillFlow using the MCP protocol.

> "It's 2026. Build. For. Agents." — Andrej Karpathy

**Key benefits:**
- **Live API** — real-time data from the SkillFlow backend, not hardcoded
- **Curated skills** across 6 business categories with performance metrics
- **Trust metrics** — success rates, run counts, ratings, and speed benchmarks
- **Zero config** — no API keys, no environment variables, just `npx`
- **Works everywhere** — Claude Desktop, Cursor, Windsurf, Copilot, Gemini CLI, and any MCP-compatible agent

## Transports

This server supports two transports:

| Transport | Use Case | Command |
|-----------|----------|----------|
| **stdio** | Local use with Claude Desktop, Cursor, etc. | `npx skillflow-mcp-server` |
| **Streamable HTTP** | Remote access via Smithery.ai, cloud agents | `skillflow-mcp-http` or `npm start:http` |

## Quick Start (stdio — Local)

### One-liner (npx)

```bash
npx skillflow-mcp-server
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "skillflow": {
      "command": "npx",
      "args": ["-y", "skillflow-mcp-server"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "skillflow": {
      "command": "npx",
      "args": ["-y", "skillflow-mcp-server"]
    }
  }
}
```

### Windsurf / VS Code / Other MCP Clients

```json
{
  "mcpServers": {
    "skillflow": {
      "command": "npx",
      "args": ["-y", "skillflow-mcp-server"]
    }
  }
}
```

### Global Installation

```bash
npm install -g skillflow-mcp-server
skillflow-mcp
```

## Available Tools

| Tool | Description |
|------|-------------|
| `search_skills` | Search for skills by keyword, category, or tag |
| `get_skill_details` | Get detailed info about a specific skill including pricing and performance |
| `list_categories` | List all skill categories |
| `get_trending_skills` | Get currently trending skills |
| `get_platform_stats` | Get overall platform statistics (skills, runs, creators, revenue) |

## Examples

Once connected, ask your AI agent:

- *"Search for skills that help with SEO content"*
- *"What are the trending skills on SkillFlow?"*
- *"Get details about the blog-seo-writer skill"*
- *"List all skill categories"*
- *"Show me the platform stats"*
- *"Find skills for lead generation"*

## Quick Start (Streamable HTTP — Remote)

### Self-hosted

```bash
npm install -g skillflow-mcp-server
PORT=3000 skillflow-mcp-http
```

### Docker

```bash
docker build -t skillflow-mcp .
docker run -p 3000:3000 skillflow-mcp
```

### Smithery.ai

Available at: [smithery.ai/server/skillflow-mcp-server](https://smithery.ai/server/skillflow-mcp-server)

### HTTP API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/mcp` | Send JSON-RPC requests (initialize, tools/list, tools/call) |
| `GET` | `/mcp` | Open SSE stream for server notifications |
| `DELETE` | `/mcp` | Terminate a session |
| `GET` | `/health` | Health check (includes live skill count) |

## Architecture

```
┌─────────────┐     MCP Protocol     ┌──────────────────┐     tRPC API     ┌──────────────┐
│  AI Agent   │ ◄──────────────────► │ SkillFlow MCP    │ ◄──────────────► │  SkillFlow   │
│ (Claude,    │  stdio / HTTP+SSE    │ Server           │   (live data)    │  Backend     │
│  Cursor...) │                       └──────────────────┘                  └──────────────┘
└─────────────┘
```

The MCP server acts as a bridge between AI coding agents and the SkillFlow marketplace. It fetches real-time data from the SkillFlow backend API with 5-minute caching for optimal performance.

## Listed On

- [Official MCP Registry](https://registry.modelcontextprotocol.io) (Anthropic)
- [npm](https://www.npmjs.com/package/skillflow-mcp-server)
- [MCP Market](https://mcpmarket.com)
- [mcpservers.org](https://mcpservers.org)
- [Glama.ai](https://glama.ai/mcp/servers)
- [Smithery.ai](https://smithery.ai/server/skillflow-mcp-server)

## Development

```bash
git clone https://github.com/rafsilva85/skillflow-mcp-server.git
cd skillflow-mcp-server
npm install
npm run build
npm start
```

## Contributing

Contributions welcome! Please open an issue or submit a PR.

## License

MIT — [Rafael Silva](https://github.com/rafsilva85)

---

Built with the [MCP SDK](https://github.com/modelcontextprotocol/sdk) | Powered by [SkillFlow](https://skillflow.builders)