API and MCP

gitmanual for code and AI agents

The same setup manuals as the website, plus search, lists and alternatives, as JSON, Markdown or MCP tools. It works without a key; a free key raises the limits and opens private repos.

Base URL: https://gitmanual.com/api/v1
MCP: https://gitmanual.com/mcp
Format: JSON (manuals also as Markdown)
Cost: Free

Your API key

Checking…

Quick start

Try it, no key needed.

curl "https://gitmanual.com/api/v1/manual?repo=ollama/ollama&os=mac&format=md"

Get a free key above, for higher limits and private repos, and send it as a header:

curl -H "Authorization: Bearer gm_your_key" \
  "https://gitmanual.com/api/v1/search?q=self-hosted&os=linux"

Or add it to your AI agent as an MCP server (Claude, Cursor, VS Code and others):

{
  "mcpServers": {
    "gitmanual": {
      "url": "https://gitmanual.com/mcp",
      "headers": { "Authorization": "Bearer gm_your_key" }
    }
  }
}

Authentication

Both headers are optional. Without them you get everything public, at the lower limit.

Header	Value	What for
`Authorization`	`Bearer gm_…`	Your gitmanual API key: higher limits, private repos and usage.
`X-GitHub-Token`	`github_pat_…`	Private repos only: your own read-only GitHub token. Needs an API key too.

Keep your key out of web pages and public code: anyone with it can use your limits. If it leaks, replace it above.

Limits

	No key	Free key
Requests (any endpoint or MCP tool)	60 an hour	1,000 an hour
…of which new repos (read from GitHub)	10 a day	200 an hour
Private repos (with your GitHub token)	No	Yes
See your usage	No	Yes

A new repo is one gitmanual hasn't read from GitHub before; it counts toward both limits. Over a limit, you get 429 with a Retry-After header in seconds. Need more? Get in touch.

Endpoints

All are GET, answer JSON and allow requests from any website (CORS). Pick your language once and every example follows; Send request runs it live.

GET/api/v1/manual

Get a setup manual

Everything the manual page shows for one repo: whether it runs on each system and why, downloads, install commands, step-by-step commands, the parts it needs, the before-you-start answers and how many people got it running.

One request. A repo read from GitHub for the first time also counts as a new repo.

Parameters

Name	About
`repo`stringRequired	owner/repo or any github.com link.
`os`mac \| windows \| linux	Only this system. Leave out for all three.
`arch`arm64 \| x64	The computer's chip, to pick the right download.
`format`md	Markdown instead of JSON, ready for an AI agent to read.

Response fields

Field	About
`repo`string	owner/repo, as GitHub spells it.
`private`boolean	True when read with your GitHub token (never saved).
`difficulty`string	Easy, Moderate or Involved.
`gotItRunning`object	How many people said it worked or they got stuck, in all and per system.
`beforeYouStart`array	Is it free, does it use paid AI, is it maintained, its track record.
`systems.{os}.verdict`yes \| maybe \| no	Whether it runs on that system; headline and reasons say why.
`systems.{os}.downloads`array	Ready-made files from its releases; recommended marks the best one.
`systems.{os}.installCommands`array	Install commands from the README (Homebrew, winget, pip…).
`systems.{os}.steps`array	Step-by-step setup from source, each with its commands.
`parts`object	Runtimes, tools, services and settings (.env) it needs.

curl "https://gitmanual.com/api/v1/manual?repo=ollama/ollama&os=mac" \
  -H "Authorization: Bearer gm_your_key"  # optional

Example response

{
  "repo": "ollama/ollama",
  "description": "Get up and running with large language models.",
  "stars": 186263,
  "private": false,
  "manual": "https://gitmanual.com/ollama/ollama",
  "difficulty": "Easy",
  "gotItRunning": { "worked": 12, "stuck": 1, "bySystem": { "mac": { "worked": 7, "stuck": 0 } } },
  "beforeYouStart": [
    { "question": "Is ollama free?", "answer": "Yes", "detail": "Open source (MIT).", "tone": "yes" }
  ],
  "systems": {
    "mac": {
      "verdict": "yes",
      "headline": "Yes, there's a macOS download",
      "downloads": [{ "name": "Ollama.dmg", "url": "https://github.com/…", "arch": null, "recommended": true }],
      "installCommands": [{ "method": "Homebrew", "command": "brew install ollama", "kind": "app" }],
      "steps": [{ "title": "Install Go", "commands": ["brew install go"] }, "…"],
      "setupScript": "https://gitmanual.com/ollama/ollama/setup/mac.sh"
    }
  },
  "parts": { "runtimes": ["Go 1.24"], "tools": ["Git"], "services": [], "envVars": [] }
}

GET/api/v1/search

Search the shelf

Every repo people have set up with gitmanual, filtered and sorted like the shelf page. Add rising=true for what's rising on GitHub this week.

One request.

Parameters

Name	About
`q`string	Words in the repo's name or description.
`os`mac \| windows \| linux	Only repos that run on this system.
`language`string	Main language as GitHub names it, e.g. "Python".
`difficulty`Easy \| Moderate \| Involved	How much setup it takes.
`minStars`number	At least this many GitHub stars.
`sort`stars \| recent \| popular \| worked	Most stars (default), recently looked up, most viewed, or most people got it running.
`rising`true	Only repos rising on GitHub this week.
`page`number	Page of results, from 1.
`perPage`number	Results per page: 20 by default, at most 50.

Response fields

Field	About
`total`number	Repos that match, across all pages.
`page, pages, perPage`number	Where you are; ask for the next with page.
`results[].repo`string	owner/repo; open its manual with /api/v1/manual.
`results[].difficulty`string	Easy, Moderate or Involved.
`results[].gotItRunning`object	How many people said it worked or got stuck.
`results[].risingThisWeek`boolean	Gaining stars fast on GitHub this week.
`results[].manual`string	The manual page on gitmanual.

curl "https://gitmanual.com/api/v1/search?q=llm&os=windows&perPage=2" \
  -H "Authorization: Bearer gm_your_key"  # optional

Example response

{
  "total": 5,
  "page": 1,
  "perPage": 2,
  "pages": 3,
  "results": [
    {
      "repo": "ggml-org/llama.cpp",
      "description": "LLM inference in C/C++",
      "stars": 133590,
      "language": "C++",
      "difficulty": "Moderate",
      "gotItRunning": { "worked": 3, "stuck": 1 },
      "risingThisWeek": false,
      "manual": "https://gitmanual.com/ggml-org/llama.cpp",
      "analyzedAt": "2026-11-06T09:12:44.000Z"
    },
    "…"
  ]
}

GET/api/v1/lists

List the lists

Every curated list: a theme (self-hosted apps, AI tools, command-line tools, MCP servers, ready-made downloads) on one system. ready is false while a list has fewer than four repos.

One request.

Response fields

Field	About
`lists[].slug`string	Use with /api/v1/lists/{slug}.
`lists[].theme`string	self-hosted-apps, ai-tools, command-line-tools, mcp-servers or apps-with-a-download.
`lists[].os`mac \| windows \| linux	The system every repo on it runs on.
`lists[].repos`number	How many repos it has (up to 60).
`lists[].ready`boolean	False while it has fewer than four repos.

curl "https://gitmanual.com/api/v1/lists" \
  -H "Authorization: Bearer gm_your_key"  # optional

Example response

{
  "lists": [
    {
      "slug": "ai-tools-windows",
      "title": "Open-source AI tools that run on Windows",
      "theme": "ai-tools",
      "os": "windows",
      "repos": 39,
      "url": "https://gitmanual.com/lists/ai-tools-windows",
      "ready": true
    },
    "…"
  ]
}

GET/api/v1/lists/{slug}

Get a list

One list and its repos (up to 60), most stars first.

One request.

Parameters

Name	About
`slug`stringRequired	In the path, from /api/v1/lists, e.g. ai-tools-windows.

Response fields

Field	About
`title, intro`string	What the list is, ready to show people.
`results[]`array	Its repos, most stars first, in the same shape as search results.

curl "https://gitmanual.com/api/v1/lists/ai-tools-windows" \
  -H "Authorization: Bearer gm_your_key"  # optional

Example response

{
  "slug": "ai-tools-windows",
  "title": "Open-source AI tools that run on Windows",
  "intro": "LLM apps, agents and AI tools from GitHub that run on Windows, with a setup manual for each.",
  "os": "windows",
  "repos": 39,
  "url": "https://gitmanual.com/lists/ai-tools-windows",
  "results": [{ "repo": "microsoft/markitdown", "stars": 94210, "…": "…" }, "…"]
}

GET/api/v1/alternatives

Find alternatives

Whether a repo runs on a system, and up to five similar repos (by shared GitHub topics) that do. Useful when the answer is no.

One request. A repo read from GitHub for the first time also counts as a new repo.

Parameters

Name	About
`repo`stringRequired	owner/repo or any github.com link.
`os`mac \| windows \| linuxRequired	The system it should run on.

Response fields

Field	About
`runsOn.verdict`yes \| maybe \| no	Whether the repo itself runs on that system.
`runsOn.headline`string	The answer in a sentence.
`alternatives[]`array	Up to five similar repos that do run there, closest first.

curl "https://gitmanual.com/api/v1/alternatives?repo=coollabsio/coolify&os=windows" \
  -H "Authorization: Bearer gm_your_key"  # optional

Example response

{
  "repo": "coollabsio/coolify",
  "os": "windows",
  "runsOn": { "verdict": "maybe", "headline": "Yes, with extra tools on Windows" },
  "alternatives": [
    {
      "repo": "gogs/gogs",
      "description": "The painless way to host your own Git service",
      "stars": 47919,
      "manual": "https://gitmanual.com/gogs/gogs"
    },
    "…"
  ]
}

MCP server

Add https://gitmanual.com/mcp (Streamable HTTP) to any MCP client. The tools match the endpoints and answer in Markdown that agents read well. Headers are the same as the API's and optional.

Tool	Inputs	What it does
`get_setup_manual`	repo, os?, arch?	A repo's setup manual, as Markdown.
`get_setup_script`	repo, os	One script that sets the repo up (bash or PowerShell).
`search_repos`	query?, os?, language?, difficulty?, sort?, rising?, page?	Search the shelf.
`get_list`	slug?	A curated list, or all of them.
`find_alternatives`	repo, os	Similar repos that run on a system.

{
  "mcpServers": {
    "gitmanual": {
      "url": "https://gitmanual.com/mcp",
      "headers": { "Authorization": "Bearer gm_your_key" }
    }
  }
}

Postman, Swagger and code generators

The whole API is described in one OpenAPI file, so you can explore it in your own tools or generate a client in any language.

PostmanImport → Link, and paste the OpenAPI link.

SwaggerEvery endpoint with a form to try it.Open in Swagger Editor ↗

OpenAPI fileFor code generators and AI agents.openapi.json ↗

Private repos

Make a fine-grained GitHub token with Contents: Read-only, for just the repos you want.

Send it as X-GitHub-Token, together with your API key:

curl -H "Authorization: Bearer gm_your_key" \
  -H "X-GitHub-Token: github_pat_…" \
  "https://gitmanual.com/api/v1/manual?repo=your-org/internal-app&format=md"

Public repos ignore the token. A private repo is read for that request only: the answer says "private": true, and it's never saved, cached or sent to an AI service. On the website, use Private repos instead.

Errors

Errors are JSON with a message you can show people: { "error": "That API key isn't valid. …" }

Status	Name	When
400	Bad request	A parameter is missing or not one of the allowed values.
401	Unauthorized	The API key is wrong, or a private repo was asked for without one.
403	Forbidden	The API key has been turned off.
404	Not found	No such repo or list, or the repo is private and no GitHub token (or the wrong one) was sent.
429	Too many requests	Over a limit. Retry-After says how many seconds to wait.
500	Server error	Something broke on our side. Try again in a moment.

What a key stores

Your GitHub username and account number, when the key was made and last used, and how many requests it has made. The key itself is stored only as a fingerprint (a SHA-256 hash), so it's shown to you once. Signing in gives gitmanual no access to your repos. Delete the key above any time; see the privacy policy.