api-mcp

A Model Context Protocol 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:

{
  "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

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

Run

The server speaks MCP over stdio:

node dist/index.js

Configure in an MCP client

Claude Code

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):

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

Example calls

Fetch JSON:

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

Create a resource with a JSON body and auth header:

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

Send a raw form-encoded body:

// 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