Listable MCP Server

Let Claude, Cursor, and other AI assistants manage your Listable directory site through natural conversation.

Listable is a platform for building directory websites — restaurant guides, business directories, travel listings, niche curated sites. Its MCP (Model Context Protocol) server exposes every site-management operation as a structured tool that AI assistants can call.

Ask the AI things like:

• *"Add 20 Italian restaurants in Brooklyn to my food directory."*
• *"Import these listings from the CSV I'm pasting."*
• *"Set the SEO meta title and description for the homepage."*
• *"Add a Categories dropdown to the header menu."*
• *"Create an About page with our mission and a list of featured listings."*

What it can do

~47 tools across these groups:

The AI is told to call `get_schema` first so its edits use the right custom fields and block types. Destructive operations (deletes, full block replacements, URL structure changes, script overwrites) prompt for confirmation before running.

Two ways to connect

If your client supports HTTP MCP transport, skip the shim entirely — see OAuth setup below. The npm package (`listable-mcp`) is only needed for stdio-only clients like Claude Desktop.

OAuth setup (no install needed)

The MCP endpoint is:

https://app.get-listable.com/api/v1/external/mcp

When a client connects without a bearer token, the server returns a `401` plus a `WWW-Authenticate` discovery hint pointing at `/.well-known/oauth-protected-resource`. The client follows it, redirects you to log in, asks you to approve scopes (including which projects to grant), and gets a token automatically. Access tokens expire after 1 hour and refresh silently for 1 month.

Claude.ai (web)

*Settings → Integrations → Add custom integration* → paste:

https://app.get-listable.com/api/v1/external/mcp

Claude.ai bounces you to Listable to log in and pick the projects the integration may access. Revoke any time from the API Keys page in your Listable admin.

Claude Code

claude mcp add --transport http listable https://app.get-listable.com/api/v1/external/mcp

Claude Code does the OAuth dance in your browser on first use. Verify with `/mcp` inside a session.

Cursor

In *Settings → MCP*, add an HTTP server:

• Name: `listable`
• URL: `https://app.get-listable.com/api/v1/external/mcp`

Cursor will trigger the OAuth flow on first connect.

Stdio fallback (this npm package)

Use this path for Claude Desktop (which doesn't support HTTP MCP yet) or any stdio-only client. You'll need to create an API key first:

1. Open *API Keys* in your Listable admin:

2. Click *Create a new API key*, name it (e.g. "Claude Desktop"), and optionally scope it to specific projects

3. Copy the key — it's only shown once

Claude Desktop

Open *Settings → Developer → Edit Config* (`claude_desktop_config.json`) and add:

{
  "mcpServers": {
    "listable": {
      "command": "npx",
      "args": ["-y", "listable-mcp"],
      "env": {
        "LISTABLE_API_TOKEN": "lst_..."
      }
    }
  }
}

Fully quit and restart Claude Desktop. Listable's tools appear in the *Search and tools* menu.

Other stdio clients

Any MCP client that launches a subprocess can run `npx -y listable-mcp` and pass `LISTABLE_API_TOKEN` in the environment.

Global install (optional)

If you'd rather not rely on `npx` resolution each launch:

npm install -g listable-mcp

Then point the client at the `listable-mcp` binary directly instead of `npx -y listable-mcp`.

Configuration

Rate limits

• Growth plan: 60 requests/minute, 750 tool calls/month
• Pro plan: 300 requests/minute, unlimited monthly calls

Hitting either limit returns a `429` with `retry_after` (per-minute) or `quota_reset_at` (monthly). For bulk work the AI prefers `bulk_create_items` (up to 100 listings/call) over many single creates.

Safety

Tool descriptions tell the AI to:

• Discover first — call `get_schema` before editing so changes use the right custom fields and block types
• Confirm destructive ops — deletes, full-page block replacements, URL structure changes, and script overwrites prompt for explicit confirmation
• Back up before editing — keep prior state in context to restore if something goes wrong
• Append, don't replace — scripts (analytics, tracking) are appended to existing content

Every tool call is logged against the project it touched. View the timeline at *Project → API* in your Listable admin — filterable by source (MCP vs REST) and retained for 30 days.

Revoking access

• OAuth grants: appear on the API Keys page alongside manually-created keys. Revoke there.
• Static API keys: revoke from the same API Keys page. The AI client will receive `401` errors on its next call.

Troubleshooting

"Unauthenticated" errors (stdio shim) — Confirm `LISTABLE_API_TOKEN` is set in the same shell or config block that launches the client. In Claude Desktop the `env` map in the JSON config must contain the key.

OAuth loop / browser doesn't redirect back — Make sure the client's redirect URL is reachable. Some clients use a localhost callback; cookies or popup blockers can interrupt the flow.

"Tool not available" — Restart the client (Claude Desktop requires a full quit and reopen). In Claude Code, run `/mcp` to confirm Listable is connected.

`403` on specific projects — Your token is scoped. OAuth: re-run the approval and select more projects. Static key: create a new one without project scoping.

Links

• Listable:
• API + MCP docs:
• Model Context Protocol:

License

MIT — see LICENSE.