# API and MCP — Neeed Directory

Canonical page: https://neeed.directory/docs/api

Read the Neeed Directory catalog from your own code or agent. Every endpoint is a GET that answers JSON and allows cross-origin requests; only live listings are returned. No key is needed.

## Endpoints

Base URL: https://neeed.directory/api/v1. OpenAPI document: https://neeed.directory/api/v1/openapi.json.

- `GET /api/v1/search` — Search or list products. Live listings, newest first. Narrow them with a full-text query and by category, label or tag; every filter is optional.
- `GET /api/v1/categories` — List categories. Every category with the number of live listings it holds, by name.
- `GET /api/v1/products/{slug}` — Get a product. One live listing by slug. A listing that is not live is a 404.

## Limits and caching

- 30 searches and 60 other calls per IP per minute, then a 429 until the minute ends.
- Answers can be served from the edge for up to five minutes, so a change to a listing takes that long to reach the API.
- Errors are a JSON object with a code and a message; a 400 adds the rejected parameters under data.issues.

## MCP server

https://neeed.directory/api/mcp — the same three reads as tools, over Streamable HTTP, stateless, no session and no key. With Claude Code: `claude mcp add --transport http neeed https://neeed.directory/api/mcp`. In any MCP client configuration: `{ "mcpServers": { "neeed": { "type": "http", "url": "https://neeed.directory/api/mcp" } } }`.

- `search_products`: Search the live listings on Neeed Directory, newest first. Every argument is optional: a full-text query over name, tagline and description, and category, label or tag slugs to narrow by. Returns products with their slug, tagline, description, website and pricing model, plus the total match count.
- `list_categories`: Every category on Neeed Directory with its slug, name and the number of live listings it holds.
- `get_product`: One live listing on Neeed Directory by slug, with its full description, website, labels, tags and pricing model.

## The Product object

- id (string (uuid))
- slug (string)
- name (string)
- punchline (string): The one-line tagline
- description (string): HTML, as the listing page renders it
- url (string (uri)): The listing on Neeed Directory
- website (string): The product's own site
- logo (string (uri) or null)
- cover (string (uri) or null)
- category (string or null): Category slug
- labels (string[]): Label slugs
- tags (string[]): Tag slugs
- product_type ("software" | "digital_product" or null)
- pricing_model ("free" | "freemium" | "paid" | "open_source" or null)
- twitter (string or null): X handle, without the @
- featured (boolean)
- listed_at (string (date-time) or null): When the listing went live

## Feeds

- https://neeed.directory/feed.xml: the 50 newest listings.
- https://neeed.directory/categories/{slug}/feed.xml: the same feed narrowed to one category.
- https://neeed.directory/sitemap.xml: every public URL, split into pages, categories, products, alternatives and weekly recaps.