What Context7 MCP is
Context7 MCP is an MCP server from Upstash that fetches current, version-specific documentation for a library and hands it to your coding agent as a tool call, so the code it writes matches the API as it is today rather than at the model's training cutoff. It is free for 1,000 calls a month and listed with a Grade A on MCPVault.
This page is the setup reference for every major client: Claude Code, Cursor, Windsurf, VS Code and Claude Desktop each get their own config block below, followed by the tools it exposes, a troubleshooting section for the errors people actually hit, and a comparison with your agent's built-in web search.
What Context7 actually does
Context7 is a documentation index run by Upstash. It resolves a library name to a Context7 ID, then returns the current, version-specific docs and code examples for that library as plain text the model can read. Your agent calls it as a tool before writing code, so the code matches today's API instead of the one in the model's training data.
It does not run your code, and it does not search the open web. It answers one question well: what does this library's documentation say right now.
The project is one of the most starred MCP servers in existence, with over 61,000 GitHub stars, MIT licensed, and a Grade A on Context7's MCPVault listing. The npm package @upstash/context7-mcp is at version 4.x, and the hosted endpoint at mcp.context7.com means you can skip the local process.
Is Context7 free?
Yes. The Free plan is $0 for 1,000 API calls a month, with or without an API key; the key raises the anonymous rate limit and stops the 429 errors that show up in long sessions. Pro is $10 per seat a month for 5,000 calls per seat, then $10 per extra 1,000 calls. Enterprise is custom. For one developer running a few agent sessions a day the free plan is enough; a team on Claude Code all day will hit 1,000 calls within the month. Prices read from context7.com/plans on 7 September 2026.
Get a free API key first
Context7 works without a key at low volume. A free key from context7.com/dashboard raises the rate limits and removes the intermittent 429 errors you will otherwise see during a long session. Every config below shows where the key goes. If you skip it, delete the --api-key argument or the Authorization header.
There is also a one-command installer that authenticates in the browser and writes the config for you:
npx ctx7 setup
Pass --cursor, --claude or --opencode to target one client. npx ctx7 remove undoes it. The manual configs below are for when you want to see exactly what lands in your config files.
Claude Code
Local process over stdio:
claude mcp add context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY
Or the hosted endpoint, which avoids the npx cold start on every session:
claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "Authorization: Bearer YOUR_API_KEY"
Add --scope project to commit the server to .mcp.json for your team, or --scope user to make it available in every project. Verify with claude mcp list, then ask Claude Code to use context7 in a prompt about any library. See the Claude Code's MCP documentation for scopes and the config file layout.
Cursor
Cursor reads ~/.cursor/mcp.json for global servers and .cursor/mcp.json inside a project for project-scoped ones. Either file:
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
}
}
}
Open Cursor Settings, then MCP, and confirm the server shows a green status with two tools. A rule many Cursor users add to .cursor/rules: "Always use Context7 to check library documentation before writing code that imports it." Without a rule, the agent decides on its own when to call the tool, and it will skip it more often than you want. This is the same server that tops the best MCP servers for Cursor list.
Windsurf
Windsurf keeps MCP config in ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
}
}
}
Reload the Cascade panel after saving. Windsurf also accepts a serverUrl field for the hosted endpoint if you prefer not to run a local process.
VS Code
VS Code uses a servers key rather than mcpServers, and it supports HTTP transports natively. In .vscode/mcp.json:
{
"servers": {
"context7": {
"type": "http",
"url": "https://mcp.context7.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
Upstash also publishes a VS Code extension (Upstash.context7-mcp on the Marketplace) that registers the server automatically. Use one or the other, not both, or you will see duplicate tools in the picker.
Claude Desktop
Claude Desktop reads claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
}
}
}
Quit and reopen the app fully. Claude Desktop can also add the hosted endpoint as a custom connector from Settings without touching the file.
Codex CLI
Codex reads ~/.codex/config.toml. Local process:
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
startup_timeout_ms = 20_000
Or the hosted endpoint:
[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }
The one-liner codex mcp add context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY writes the first block for you. If startup times out, raise startup_timeout_ms to 40_000; on Windows use the absolute path to npx.cmd.
Gemini CLI
Gemini CLI reads ~/.gemini/settings.json:
{
"mcpServers": {
"context7": {
"httpUrl": "https://mcp.context7.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY",
"Accept": "application/json, text/event-stream"
}
}
}
}
Swap httpUrl and headers for "command": "npx", "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"] to run it locally instead.
The two tools
resolve-library-id takes a library name such as next.js and returns the Context7 ID, in this case /vercel/next.js, along with a short description and the number of snippets indexed. The agent calls this first when it does not know the ID.
query-docs takes a library ID and a natural-language query such as "middleware redirect" and returns the matching documentation sections and code examples. Version pinning works by including the version in the prompt: "Next.js 14 middleware, use context7" returns the 14.x docs, not the latest.
You can skip the first tool by naming the ID in your prompt: use library /supabase/supabase for auth setup. That saves one round trip and removes the chance of the resolver picking a fork instead of the project you meant.
See Context7 on MCPVault for grades, tools and install details at the Context7 listing.
Troubleshooting
429 Too Many Requests. You are hitting the anonymous rate limit. Create a free key and add it to the config. The limit resets within minutes, so a session is rarely blocked for long.
"Library not found" or an unrelated library returned. The resolver picked the wrong match for a generic name. Give it the GitHub owner and repo, or look the ID up on context7.com and pass it with the slash syntax. Libraries not yet indexed can be submitted on the Context7 site and usually appear within a day.
ERR_MODULE_NOT_FOUND or a stale version. npx cached an older package. Run npx -y @upstash/context7-mcp@latest once, or clear the cache with npx clear-npx-cache, then restart the client.
Server shows red in Cursor or Windsurf on Windows. Wrap the command: "command": "cmd", "args": ["/c", "npx", "-y", "@upstash/context7-mcp"]. Cursor spawns the process without a shell, so the .cmd shim for npx is not found otherwise.
Node version errors. The server needs Node 18 or newer. Check with node -v; version managers sometimes expose an older Node to GUI apps than to your terminal.
The agent never calls it. Add "use context7" to your prompt, or write a rule. The server only helps when the model decides to use it.
Context7 vs built-in docs search vs Serena
Most agents can already search the web, and many Claude Code users also run Serena. The three retrieve different things.
| Context7 | Built-in web search | Serena | |
|---|---|---|---|
| Source | Official docs, indexed and cleaned | Any page, including outdated blog posts | Your own codebase, through a language server |
| Output | Snippets plus code, ready for context | Raw pages the model has to parse | Symbols: definitions, references, hierarchies |
| Versioning | Pin a version in the prompt | Whatever ranks today | Whatever is checked out |
| Token cost | Low, only the relevant sections | High, whole pages with navigation | Low, one symbol at a time |
| Coverage | Thousands of libraries, not everything | Everything, at lower precision | Your repo only |
Use Context7 for "how does this API work right now" questions. Use web search for "why is this error happening" questions, where a GitHub issue or a forum thread is the answer. Running both is normal.
Context7 also ships a second mode, CLI plus Skills, where the agent runs ctx7 docs <id> <query> as a shell command instead of an MCP tool. It exists for agents without MCP support and for CI scripts. For the clients on this page, MCP mode is the right choice.
Frequently Asked Questions
Is Context7 free to use?
Yes: 1,000 API calls a month on the Free plan, Pro at $10 per seat for 5,000 calls. See the pricing section above.
Does Context7 work without an API key?
Yes, at low volume. The anonymous tier is rate limited, and long agent sessions will hit 429 errors. A free key from the Context7 dashboard removes that, and every config on this page shows where it goes.
Can Context7 fetch docs for a specific library version?
Yes. Put the version in your prompt, for example "Tailwind v4 config, use context7", and the query-docs tool returns that version's documentation. This matters for projects pinned to an older major release.
Should I run Context7 locally or use the hosted endpoint?
The hosted endpoint at mcp.context7.com is faster to start and needs no Node install. The local npx process works offline-tolerant for the config but still needs network to fetch docs. Claude Code, VS Code and Claude Desktop handle the hosted version natively; Cursor and Windsurf work with either.
What clients does Context7 support?
More than 30, including Claude Code, Cursor, Windsurf, VS Code, Claude Desktop, Cline, Zed, Codex, OpenCode and ChatGPT in developer mode. The five above cover most developers; the full list with configs is in Context7's own client docs. You can also read how MCPVault assigns quality grades to servers like this one.
Your server in the vault.
If you built an MCP server, claim the listing and get it in front of developers who are actively looking. Free to claim. Verification is free during early access and earns a do-follow link to your project.
Claim your listing or submit a server if it is not indexed yet.