# api-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an
LLM make **arbitrary HTTP API requests** using any method — `GET`, `POST`,
`PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS` — against any URL.

It exposes one general-purpose tool plus thin per-method convenience wrappers, so
a model can call whatever REST/HTTP API it needs with full control over headers,
query parameters, and request bodies.

## Tools

| Tool | Description |
| --- | --- |
| `http_request` | The general tool. Takes a `method` argument plus everything below. |
| `get` / `post` / `put` / `patch` / `delete` | Convenience wrappers with the method fixed. |

### Arguments

All tools accept the same arguments (the per-method tools omit `method`):

| Argument | Type | Description |
| --- | --- | --- |
| `method` | enum | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS` (only on `http_request`). |
| `url` | string | Full request URL including `http://` or `https://`. **Required.** |
| `headers` | object | Request headers, e.g. `{ "Authorization": "Bearer …", "Accept": "application/json" }`. |
| `query` | object | Query-string params, URL-encoded and appended to the URL. |
| `body` | string | Raw request body sent as-is (form-encoded, plain text, etc.). Ignored for `GET`/`HEAD`. |
| `json` | any | JSON-serializable value sent as the body with `Content-Type: application/json`. Takes precedence over `body`. Ignored for `GET`/`HEAD`. |
| `timeout` | number \| null | Request timeout in **seconds**. `null`, `0`, or omitted uses the default (30s). Capped at 900s (15 minutes) — larger values are clamped. |
| `follow_redirects` | boolean | Follow HTTP redirects (default `true`). |
| `max_response_bytes` | number | Cap on response body bytes read back (default `1000000`). Larger bodies are truncated. |
| `response_encoding` | enum | `auto` (default), `text`, or `base64`. Controls how the body is encoded — see below. |

### Response

Each call returns a JSON object with:

```jsonc
{
  "request": { "method": "POST", "url": "https://api.example.com/items?x=1" },
  "status": 201,
  "statusText": "Created",
  "ok": true,
  "elapsed_ms": 142,
  "headers": { "content-type": "application/json", ... },
  "body_bytes": 87,
  "body_truncated": false,
  "body_encoding": "utf-8",
  "body": "{\"id\":\"abc\"}"
}
```

A non-2xx status is returned as a normal (non-error) result — it's real
information about the API, not a tool failure. Only network errors, timeouts,
and invalid URLs are reported as tool errors.

### Binary & non-text responses

The `body` is returned as either UTF-8 text or base64, and `body_encoding`
tells you which. With the default `response_encoding: "auto"`:

- Textual content types (`text/*`, and `application/*` subtypes containing
  `json`, `xml`, `javascript`, `csv`, `yaml`, `svg`, etc.) are decoded as
  **UTF-8**.
- Everything else (images, PDFs, archives, `application/octet-stream`, …) is
  returned as **base64**.
- When the response has no `Content-Type`, the bytes are sniffed for NUL bytes
  to guess text vs. binary.

Override the heuristic with `response_encoding`:

- `"text"` — always decode as UTF-8.
- `"base64"` — always base64-encode (useful when a server mislabels a binary
  payload as text).

## Install & build

```bash
npm install    # also builds via the prepare script
npm run build  # or build explicitly
```

## Run

The server speaks MCP over stdio:

```bash
node dist/index.js
```

## Configure in an MCP client

### Claude Code

```bash
claude mcp add api-mcp -- node /absolute/path/to/api-mcp/dist/index.js
```

### Claude Desktop / generic client

Add to your MCP config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "api-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/api-mcp/dist/index.js"]
    }
  }
}
```

## Example calls

Fetch JSON:

```jsonc
// tool: get
{ "url": "https://api.github.com/repos/anthropics/anthropic-sdk-python" }
```

Create a resource with a JSON body and auth header:

```jsonc
// tool: post
{
  "url": "https://api.example.com/v1/items",
  "headers": { "Authorization": "Bearer sk-…" },
  "json": { "name": "widget", "qty": 3 }
}
```

Send a raw form-encoded body:

```jsonc
// tool: http_request
{
  "method": "PUT",
  "url": "https://api.example.com/v1/items/42",
  "headers": { "Content-Type": "application/x-www-form-urlencoded" },
  "body": "name=widget&qty=5"
}
```

## Security note

This server can reach **any** URL the host machine can reach, including internal
network addresses, using whatever credentials the model supplies in headers.
Run it only in trusted contexts and be mindful of what URLs and secrets you
allow a model to send.

## License

MIT