API.SH MCP Server
Officialby API-SH
README.md
# API.SH MCP server
[](https://www.npmjs.com/package/@api.sh/mcp)
[](https://github.com/API-SH/apish-mcp/actions/workflows/test.yml)
[](LICENSE)
[API.SH](https://api.sh/?utm_source=github&utm_medium=readme) turns public web pages from around 1,000 websites into clean JSON: search engines, social media, e-commerce, real estate, jobs, travel, news and sports (Google, Amazon, TikTok, Zillow, LinkedIn and more). This MCP server lets an AI assistant find the right endpoint, read its parameters and call it for you.
There are two ways to connect:
1. **Remote (recommended).** Point your client at `https://mcp.api.sh/mcp`. Nothing to install. Sign in with OAuth, or send your API key as a Bearer token.
2. **Local.** Run `npx -y @api.sh/mcp`, the package in this repository. Use it when your client only runs local (stdio) MCP servers.
The local server is a thin bridge: it forwards every request to `https://mcp.api.sh/mcp` with your key. You get exactly the same tools, descriptions and results as the remote server, and new tools appear without an update.
## Get an API key
[Sign up](https://app.api.sh/signup?utm_source=github&utm_medium=readme) and copy a key from the dashboard. Every account gets free monthly credits, and failed calls are free.
## Option 1: remote server
**Claude Desktop and claude.ai:** Settings → Connectors → Add custom connector. Enter `https://mcp.api.sh/mcp` and sign in.
**Claude Code:**
```sh
claude mcp add --transport http apish https://mcp.api.sh/mcp
# or with a key instead of OAuth:
claude mcp add --transport http apish https://mcp.api.sh/mcp --header "Authorization: Bearer your-api-key"
```
**Cursor** (`~/.cursor/mcp.json`):
```json
{
"mcpServers": {
"apish": {
"url": "https://mcp.api.sh/mcp"
}
}
}
```
**VS Code** (`.vscode/mcp.json`):
```json
{
"servers": {
"apish": {
"type": "http",
"url": "https://mcp.api.sh/mcp"
}
}
}
```
**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
```json
{
"mcpServers": {
"apish": {
"serverUrl": "https://mcp.api.sh/mcp"
}
}
}
```
To skip OAuth in any client that supports headers, add `"headers": { "Authorization": "Bearer your-api-key" }` next to the URL.
## Option 2: local server (npx)
Needs Node.js 20 or newer. Every client uses the same command, `npx -y @api.sh/mcp`, with your key in `APISH_API_KEY`.
**Claude Desktop** (`claude_desktop_config.json`, open it from Settings → Developer → Edit Config):
```json
{
"mcpServers": {
"apish": {
"command": "npx",
"args": ["-y", "@api.sh/mcp"],
"env": { "APISH_API_KEY": "your-api-key" }
}
}
}
```
**Cursor** (`~/.cursor/mcp.json`) and **Windsurf** (`~/.codeium/windsurf/mcp_config.json`) use the same `mcpServers` block as Claude Desktop above.
**VS Code** (`.vscode/mcp.json`). VS Code asks for the key once and stores it securely:
```json
{
"inputs": [
{ "type": "promptString", "id": "apish-key", "description": "API.SH API key", "password": true }
],
"servers": {
"apish": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@api.sh/mcp"],
"env": { "APISH_API_KEY": "${input:apish-key}" }
}
}
}
```
**Claude Code:**
```sh
claude mcp add apish --env APISH_API_KEY=your-api-key -- npx -y @api.sh/mcp
```
On Windows, if your client cannot find `npx`, use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "@api.sh/mcp"]`.
### Environment variables
| Variable | Required | Default | What it does |
| --- | --- | --- | --- |
| `APISH_API_KEY` | yes | | Your API.SH API key. Sent as `Authorization: Bearer <key>`. |
| `APISH_MCP_URL` | no | `https://mcp.api.sh/mcp` | The remote MCP endpoint. |
| `APISH_TIMEOUT_MS` | no | `300000` | How long to wait for one request, in milliseconds. |
The server writes status and errors to stderr. If the key is missing or rejected, it exits with a clear message that your client shows in its MCP log.
## Tools
The tools come from the hosted server, so this list may grow. The main ones:
| Tool | What it does |
| --- | --- |
| `search_apis` | Search the catalog by site or data type. Returns routes, required parameters and credit price. |
| `get_endpoint` | Full details of one endpoint: every parameter with examples, and its price. |
| `call_api` | Run an endpoint and return its JSON. This is the only tool that spends credits. |
| `get_balance`, `get_usage`, `list_logs`, `get_log` | Credits, spending and your recent calls. `get_log` returns a past response again for free. |
| `set_spend_limits`, `list_keys`, `create_key`, `revoke_key` | Spend limits and API keys. |
| `request_api` | Ask for a site that is not in the catalog yet. |
## Example prompts
- "Find the API.SH endpoint for Amazon product details, then get the price and rating for this product: <paste an Amazon product URL>"
- "Get the top Google results for 'best espresso machine' in the US and summarise what the first five pages recommend."
- "Pull the last 20 videos from the TikTok account @nasa and tell me which got the most views."
- "Look up this Zillow listing and show its price history: <paste a Zillow listing URL>"
- "How many credits do I have left, and what did I spend them on this week?"
## Use it from code
The package also exports the bridge, if you want to embed it:
```js
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { connectRemote, createBridge } from "@api.sh/mcp";
const remote = await connectRemote({ apiKey: process.env.APISH_API_KEY });
await createBridge(remote).connect(new StdioServerTransport());
```
## Development
```sh
npm ci
npm test # build and run the offline tests
APISH_API_KEY=your-api-key npm run test:live # one free search through the real server
```
The live test lists the tools and makes one `search_apis` call, which spends no credits.
## Links
- MCP setup guide: https://api.sh/mcp?utm_source=github&utm_medium=readme
- API docs: https://api.sh/docs?utm_source=github&utm_medium=readme
- Live catalog (free, no key): https://api.api.sh/catalog
- Status: https://status.api.sh/?utm_source=github&utm_medium=readme
- Support: support@api.sh
## License
[MIT](LICENSE)
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessOutdated data