hikerapi-mcp

MCP server for HikerAPI — Instagram data API. Available on npm: hikerapi-mcp.

Generates MCP tools from the HikerAPI OpenAPI spec at startup. HikerAPI only exposes read (GET) endpoints — each tool maps 1:1 to one of them (GET /v2/user/by/username → get_v2_user_by_username). By default you get a core set of ~45 tools, one per task, each with a description that tells the assistant when to use it; HIKERAPI_TOOLS=all exposes every non-deprecated endpoint (100+).

Get 100 Free API Requests

Sign up with this link and get 100 free HikerAPI requests — no credit card required. Enough to wire up the MCP server, try a few prompts in Claude/Cursor/Codex, and evaluate the data quality before committing.

Get your free 100 requests here

Quick start

1. Get an API key at hikerapi.com/tokens.
2. Add the server to your AI assistant.
3. Ask your assistant something like:
   • "Get the Instagram profile for @nasa."
   • "Find the top 5 recent posts under the hashtag #photography."
   • "Show stories for the user with id 25025320."

Claude Code

claude mcp add hikerapi -e HIKERAPI_KEY=your-api-key -- npx -y hikerapi-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "hikerapi": {
      "command": "npx",
      "args": ["-y", "hikerapi-mcp"],
      "env": {
        "HIKERAPI_KEY": "your-api-key"
      }
    }
  }
}

Cursor / Windsurf

Same shape as Claude Desktop — put the block under mcpServers in the app's MCP config file.

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "hikerapi": {
      "command": "npx",
      "args": ["-y", "hikerapi-mcp"],
      "env": {
        "HIKERAPI_KEY": "your-api-key"
      }
    }
  }
}

OpenAI Codex

Append to ~/.codex/config.toml:

[mcp_servers.hikerapi]
command = "npx"
args = ["-y", "hikerapi-mcp"]

[mcp_servers.hikerapi.env]
HIKERAPI_KEY = "your-api-key"

Tools

Tools are generated at startup from the live HikerAPI OpenAPI spec.

HikerAPI has 100+ GET endpoints, and most of them are version variants of the same call (v1 / v2 / gql / g2). Handing all of them to an assistant makes it pick the wrong one, so the default core set keeps one endpoint per task:

| Group | Tools | Examples | | ------------------------ | ----- | -------------------------------------------------------------------------------- | | Profiles | 16 | get_v2_user_by_username, get_gql_user_medias, get_g2_user_followers | | Posts, comments, likers | 8 | get_v2_media_info_by_url, get_v2_media_comments, get_v2_media_likers | | Search | 7 | get_v2_fbsearch_accounts, get_v2_fbsearch_reels, get_v1_search_hashtags | | Hashtags | 4 | get_v2_hashtag_medias_top, get_v2_hashtag_medias_recent | | Locations | 3 | get_g2_location_by_id, get_v1_location_medias_recent_chunk | | Stories, highlights, links | 5 | get_v2_story_by_url, get_v2_highlight_by_id, get_v1_share_by_url | | Audio | 1 | get_v2_track_by_id |

Core tools carry hand-written descriptions (what the tool does, when to prefer a sibling, pagination, billing) and every tool is annotated read-only. The list lives in src/curated.ts.

Set HIKERAPI_TOOLS=all to expose every non-deprecated endpoint instead — same tool names as before, so existing prompts keep working. Tool names mirror their endpoint (GET /v2/user/by/username → get_v2_user_by_username); call tools/list over MCP for the current list with parameter schemas. Legacy and System groups are excluded in both modes.

Configuration

| Variable | Description | Required | | ----------------------------- | -------------------------------------------------------------------------------------- | -------- | | HIKERAPI_KEY | Your HikerAPI access key (sent as x-access-key header) | yes | | HIKERAPI_URL | Base URL. Default: https://api.hikerapi.com (alias https://api.instagrapi.com) | no | | HIKERAPI_SPEC_URL | OpenAPI spec URL. Default: ${HIKERAPI_URL}/openapi.json | no | | HIKERAPI_TOOLS | core (default): curated set, one tool per task. all: every non-deprecated endpoint | no | | HIKERAPI_TAGS | Whitelist: only include operations with these tags (comma-separated) | no | | HIKERAPI_EXCLUDE_TAGS | Blacklist: additional tags to exclude (on top of default Legacy,System) | no | | HIKERAPI_TIMEOUT_MS | Per-request timeout for API calls. Default: 30000 | no | | HIKERAPI_SPEC_TIMEOUT_MS | Timeout for the startup spec fetch. Default: 60000 | no | | HIKERAPI_SPEC_RETRY_DELAY_MS | Base delay between the 3 startup spec fetch attempts. Default: 2000 | no | | HIKERAPI_MAX_RESPONSE_BYTES | Max bytes read from each API response. Default: 10485760 (10 MB) | no | | HIKERAPI_MAX_SPEC_BYTES | Max bytes read from the OpenAPI spec. Default: 8388608 (8 MB) | no |

Legacy and System tags are excluded by default. Deprecated operations are also skipped.

If HIKERAPI_URL points to a host other than api.hikerapi.com or api.instagrapi.com, the server prints a warning on startup — your key will be sent there, so only use it for a self-hosted or proxied HikerAPI.

Requests are sent with User-Agent: hikerapi-mcp/<version>.

Example — expose every endpoint of the most common groups:

"env": {
  "HIKERAPI_KEY": "...",
  "HIKERAPI_TOOLS": "all",
  "HIKERAPI_TAGS": "User Profile,Post Details,Search,Hashtags,Stories"
}

How it works

AI Assistant ←stdio→ hikerapi-mcp ──https──> api.hikerapi.com
                          │
                          └─ fetches /openapi.json once on startup,
                             builds one MCP tool per GET endpoint
                             (core set by default)

Tool arguments map to the endpoint's query and path parameters. The response body is returned as-is (JSON text). Non-2xx responses are surfaced as tool errors with the HTTP status and body.

Development

git clone https://github.com/subzeroid/hikerapi-mcp.git
cd hikerapi-mcp
npm install
npm run build
HIKERAPI_KEY=your-key node dist/index.js

Run in watch mode:

HIKERAPI_KEY=your-key npm run dev

Run tests (unit + stdio smoke tests against a local mock server, no network/API key required):

npm test

License

MIT