# 🔍 Skills Search MCP

<div align="center">

[![PyPI Version](https://img.shields.io/pypi/v/skills-search-mcp?color=blue)](https://pypi.org/project/skills-search-mcp/)
[![Python Version](https://img.shields.io/python/python-3.10+?color=green)](https://pypi.org/project/skills-search-mcp/)
[![License](https://img.shields.io/pypi/l/skills-search-mcp?color=orange)](LICENSE)
[![GitHub Stars](https://img.shields.io/github/stars/luiism/skills-search-mcp)](https://github.com/luiism/skills-search-mcp/stargazers)

*A powerful MCP server that brings the [skills.sh](https://skills.sh) ecosystem directly to your AI agents*

</div>

---

## ✨ Why Skills Search MCP?

> *"The best AI agents are those with the right skills."*

Finding and installing the right skills for your AI agents shouldn't be a manual research project. **Skills Search MCP** bridges your AI agents directly to the open-source skills ecosystem, making it effortless to discover, install, and manage skills—all from within your agent workflow.

---

## 🚀 Features

- 🔎 **Smart Discovery** — Search skills by technologies (React, Python, Docker, etc.) or task domains (testing, deployment, linting)
- 📦 **Full Management** — Install, uninstall, and update skills without leaving your agent
- ⚡ **Parallel Search** — Lightning-fast async searches across multiple technologies
- 🎯 **Type-Safe** — Built with Pydantic for robust input validation
- 🧹 **Clean Output** — Automatically strips ANSI codes for readable responses
- 🔌 **Universal CLI Access** — Run any `skills` command directly when needed

---

## 📋 Available Tools

| Tool | Description |
|------|-------------|
| `find_useful_skills` | Discover skills by technologies and task domain |
| `list_installed_skills` | See what skills are already installed |
| `get_skill_info` | Get details about a specific skill |
| `install_skill` | Install a skill locally |
| `uninstall_skill` | Remove a skill |
| `update_skills` | Update installed skills to latest versions |
| `run_skill_command` | Execute raw `skills` CLI commands |

---

## 🛠️ Installation

### Prerequisites

- Python 3.10+
- Node.js & npm (for the `skills` CLI)

### Install Dependencies

```bash
pip install fastmcp pydantic
```

Or with uv:

```bash
uv pip install fastmcp pydantic
```

### Install the Skills CLI (if you haven't)

```bash
npm install -g @modelcontextprotocol/skills
```

---

## ⚡ Quick Start

### 1. Run the Server

```bash
PYTHONPATH=src python3 src/skills_search_mcp/server.py
```

### 2. Connect to Claude Desktop (macOS)

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "skills-search": {
      "command": "python3",
      "args": ["-P", "/path/to/skills-mcp/src", "src/skills_search_mcp/server.py"]
    }
  }
}
```

### 3. Connect to Cursor

Add to Cursor settings (or `cursor.mcp.json`):

```json
{
  "mcpServers": {
    "skills-search": {
      "command": "python3",
      "args": ["-P", "/path/to/skills-mcp/src", "src/skills_search_mcp/server.py"]
    }
  }
}
```

---

## 💡 Usage Examples

### Find React Skills

```
find_useful_skills(technologies=["react"])
```

### Find Testing Skills for Python

```
find_useful_skills(technologies=["python"], task_domain="testing")
```

### List Installed Skills

```
list_installed_skills()
```

### Install a Skill

```
install_skill(skill_url="vercel-labs/agent-skills@vercel-react-best-practices")
```

### Check for Updates

```
update_skills(update_all=True)
```

---

## 🔧 Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `SKILLS_TIMEOUT` | Timeout for skills commands (seconds) | 60 |

---

## 🤝 Contributing

Contributions are welcome! Here's how you can help:

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request

---

## 📚 Resources

- [skills.sh](https://skills.sh) — Browse the skills ecosystem
- [MCP Documentation](https://modelcontextprotocol.io) — Learn about MCP
- [FastMCP](https://github.com/modelcontextprotocol/python-sdk) — Python SDK

---

## ⭐ Show Your Support

If this project helps you build better AI agents, give it a ⭐️!

[![GitHub Stars](https://img.shields.io/github/stars/luiism/skills-search-mcp)](https://github.com/luiism/skills-search-mcp/stargazers)

---

<div align="center">

**Built with ❤️ for the AI agent community**

</div>