API Documentation

Access the Skillful.sh database programmatically. All endpoints return JSON.

Unauthenticated

100 requests/min

Authenticated

500 requests/min

Base URL

https://skillful.sh/api/v1

Endpoints

GET/api/v1/items

List and filter items (MCP servers, skills, agents) with pagination.

Parameters

typestringmcp_server | skill | agent

categorystringFilter by category name

searchstringFull-text search query

sortstringrecent | directoryCount | stars | name

pagenumberPage number (default: 1)

limitnumberItems per page (default: 20, max: 100)

Example

curl "https://skillful.sh/api/v1/items?type=mcp_server&sort=stars&limit=10"

GET/api/v1/items/:slug

Get detailed information about a specific item by its slug.

Example

curl "https://skillful.sh/api/v1/items/filesystem-mcp"

GET/api/v1/items/facets

Get available filter values with counts for building filter UIs.

Parameters

typestringmcp_server | skill | agent (default: mcp_server)

Example

curl "https://skillful.sh/api/v1/items/facets?type=mcp_server"

GET/api/v1/search

Global search across all item types.

Parameters

qstringSearch query (required)

typestringFilter by type

limitnumberMax results (default: 20)

Example

curl "https://skillful.sh/api/v1/search?q=filesystem&type=mcp_server"

GET/api/v1/stats

Get aggregate statistics about the Skillful.sh database.

Example

curl "https://skillful.sh/api/v1/stats"

Response Format

All responses follow this structure:

{
  "items": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 6420,
    "totalPages": 321
  }
}

Item Schema

{
  "slug": "filesystem-mcp",
  "name": "Filesystem MCP",
  "type": "mcp_server",
  "description": "MCP server for filesystem operations",
  "category": "File Systems",
  "tags": ["filesystem", "mcp", "file-operations"],
  "author": "modelcontextprotocol",
  "repositoryUrl": "https://github.com/...",
  "license": "MIT",
  "stats": {
    "githubStars": 1250,
    "githubForks": 180,
    "npmWeeklyDownloads": 5400,
    "directoryCount": 8,
    "lastCommitDate": "2026-03-10T...",
    "contributorCount": 25
  },
  "securityScore": {
    "grade": "A",
    "overallScore": 92
  },
  "isVerified": true,
  "isFeatured": false
}

Error Codes

400Bad Request — Invalid parameters

401Unauthorized — Authentication required

404Not Found — Resource does not exist

429Rate Limited — Too many requests

500Server Error — Something went wrong