Context7 MCP Server: Complete Setup Guide, Configuration & Best Practices

What Is Context7 MCP Server?

Context7 MCP Server is an open-source Model Context Protocol (MCP) server that gives AI coding assistants access to live, version-accurate library documentation at the moment they need it. Instead of relying on potentially stale training data, your AI client — Claude, Cursor, or any MCP-compatible host — can call Context7 to fetch the exact API docs, usage examples, and changelog entries for any library you're working with.

In practice, this means fewer hallucinated method signatures, fewer "this API changed in v3" mistakes, and dramatically more accurate code suggestions for libraries that evolve quickly (React, Next.js, LangChain, Prisma, etc.).

The short version: Context7 is a documentation-as-a-tool layer that plugs into your AI client via MCP, bridging the gap between a model's training cutoff and the current state of the libraries you actually use.

How Context7 Works Under the Hood

Understanding the architecture prevents a class of configuration mistakes that trip up most developers.

┌─────────────────────┐        stdio / JSON-RPC        ┌──────────────────────────┐
│   AI Client         │ ◄────────────────────────────► │  Context7 MCP Server     │

│ (Claude Desktop, │ │ (Node.js, runs locally) │ │ Cursor, etc.) │ └──────────┬───────────────┘ └─────────────────────┘ │ HTTPS REST ▼ ┌─────────────────────────┐ │ Context7 Cloud API │ │ (documentation index, │ │ crawl engine, │ │ version resolver) │ └─────────────────────────┘

**Key architectural facts:**

- The MCP server runs **locally** as a child process spawned by your AI client over stdio.
- Communication between client and server uses **JSON-RPC 2.0** messages over stdin/stdout — no local port is opened.
- The server makes outbound HTTPS calls to the **Context7 Cloud API** to resolve library IDs and fetch documentation.
- Your source code and conversation context **never leave your machine** — only library names and topic queries are sent to Context7.
- Process lifetime is tied to the client — when you close Claude Desktop, the MCP server process exits.

This stdio-based transport is simpler than HTTP/SSE transports but means the server must be installed and executable on the same machine as the client.

---

## Prerequisites

Before you start:

- **Node.js 18+** — Context7 MCP Server is a Node.js package. Run `node --version` to confirm.
- **npm 9+ or npx** — Used to run or install the package.
- **A Context7 API key** — Obtainable at [context7.com](https://context7.com). Free tier is available.
- **An MCP-compatible client** — Claude Desktop, Cursor, Windsurf, or any host that supports the MCP stdio transport.

> **Why Node.js 18+?** The package uses the native `fetch` API introduced in Node.js 18. Running on Node.js 16 will produce a `fetch is not defined` runtime error.

---

## Installation

### Option 1: npx (Recommended for Most Developers)

The fastest path — no global install required, always uses the latest version:

```bash
# Test that it works before adding to any client config
CONTEXT7_API_KEY=your_api_key_here npx -y @upstash/context7-mcp

You should see the server start and output its capabilities as JSON. Press Ctrl+C to stop.

Option 2: Global npm Install

Better for teams with strict version pinning:

npm install -g @upstash/context7-mcp

# Verify installation
context7-mcp --version

Option 3: Clone and Build from Source

Useful when you want to inspect or patch the code:

git clone https://github.com/upstash/context7
cd context7/packages/mcp
npm install
npm run build

# Run the built binary
CONTEXT7_API_KEY=your_key node dist/index.js

Getting Your Context7 API Key

1. Visit context7.com and sign up.
2. Navigate to Settings → API Keys.
3. Create a new key and copy it immediately — it won't be shown again.
4. Store it in a password manager or secrets vault, not in a .env file committed to version control.

Security note: Your API key authenticates all outbound requests from the MCP server. If it leaks, anyone can exhaust your quota. Treat it like a database password.

Claude Desktop Configuration

Claude Desktop reads MCP server configuration from a JSON file. The file location varies by operating system:

Minimal Configuration (npx)

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {
        "CONTEXT7_API_KEY": "your_api_key_here"
      }
    }
  }
}

Production-Grade Configuration (Pinned Version)

For teams where stability matters more than always-latest:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@1.4.1"],
      "env": {
        "CONTEXT7_API_KEY": "your_api_key_here",
        "CONTEXT7_LOG_LEVEL": "warn"
      }
    }
  }
}

Using a Globally Installed Binary

If you installed with npm install -g:

{
  "mcpServers": {
    "context7": {
      "command": "context7-mcp",
      "args": [],
      "env": {
        "CONTEXT7_API_KEY": "your_api_key_here"
      }
    }
  }
}

After editing the config file: Fully quit Claude Desktop (don't just close the window — use Quit from the menu or taskbar) and relaunch it. Claude Desktop only reads this file at startup.

Verifying Claude Desktop Sees Context7

1. Open Claude Desktop.
2. In any conversation, look for the tool icon (hammer) in the input area.
3. Click it — you should see resolve-library-id and fetch-library-docs listed.
4. If the tools don't appear, check the Logs section under Settings for MCP server errors.

Cursor Configuration

Cursor supports MCP servers through its own settings file located at:

• macOS/Linux: ~/.cursor/mcp.json
• Windows: %USERPROFILE%\.cursor\mcp.json

Cursor mcp.json Configuration

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {
        "CONTEXT7_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor also supports project-level MCP config via .cursor/mcp.json in your project root. This is ideal for team repositories where everyone should use the same MCP tools:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@1.4.1"],
      "env": {
        "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
      }
    }
  }
}

The ${CONTEXT7_API_KEY} syntax tells Cursor to read the value from the system environment, so each developer sets the variable in their shell profile rather than hardcoding it in the shared config.

Team setup workflow:

1. Commit .cursor/mcp.json (without the key).
2. Each developer adds export CONTEXT7_API_KEY=their_key to their ~/.zshrc or ~/.bashrc.
3. Done — no secret management complexity in the repo.

Other MCP Clients

Context7 works with any client that supports the MCP stdio transport. The configuration pattern is always the same: specify the command, arguments, and the CONTEXT7_API_KEY environment variable.

Windsurf (Codeium)

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {
        "CONTEXT7_API_KEY": "your_api_key_here"
      }
    }
  }
}

VS Code with Copilot (MCP Preview)

{
  "mcp": {
    "servers": {
      "context7": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@upstash/context7-mcp"],
        "env": {
          "CONTEXT7_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Available Tools

Context7 MCP Server exposes exactly two tools. Understanding their purpose and parameters prevents misuse.

Tool 1: resolve-library-id

Purpose: Converts a human-readable library name into a Context7 library ID (slug), which is required by fetch-library-docs.

Input parameters:

Example tool call:

{
  "name": "resolve-library-id",
  "arguments": {
    "libraryName": "next.js"
  }
}

Example response:

{
  "results": [
    {
      "id": "/vercel/next.js",
      "name": "Next.js",
      "description": "The React Framework for the Web",
      "versions": ["14.0", "13.5", "13.4"],
      "stars": 118000
    }
  ]
}

When to use directly: You typically don't call this manually — the LLM calls it automatically. But understanding it helps when you need to debug why the wrong library is being fetched.

Tool 2: fetch-library-docs

Purpose: Fetches actual documentation content — API references, guides, examples — for a specific library.

Input parameters:

Example tool call:

{
  "name": "fetch-library-docs",
  "arguments": {
    "libraryId": "/vercel/next.js",
    "topic": "server actions form handling",
    "tokens": 8000
  }
}

Design note: The two-tool pattern (resolve then fetch) is intentional. It separates ambiguous name resolution (which may return multiple candidates) from the actual content fetch, giving the LLM an opportunity to confirm it's using the right library before making a content request.

Typical Use Cases

1. Accurate Code Generation for Rapidly Changing Libraries

When you ask Claude to write code using Next.js Server Actions, Prisma's $transaction API, or LangChain's LCEL syntax, the model's training data may reflect an outdated version. Context7 fetches current docs so generated code matches the library version you're actually running.

Prompt pattern that works well:

Using context7, fetch the latest Next.js docs on Server Actions with form handling, 
then write a contact form component that submits via a server action.

2. Migration Assistance

When migrating between major versions (React 17→18, Next.js Pages→App Router, Prisma 4→5), ask the AI to fetch docs for the new version before generating migration code.

3. Debugging with Accurate API References

"Why is this Prisma query failing?" is much better answered when the AI has the current Prisma query API docs in context rather than guessing from training data.

4. Documentation-Driven Development

Start a feature by having the AI pull the relevant library docs first, then generate implementation code — rather than having it hallucinate method signatures and discover errors at runtime.

Environment Variables Reference

Common Errors and Troubleshooting

Error: CONTEXT7_API_KEY is not set

Cause: The server starts but can't find the API key in its environment.

Fix: Confirm the key is set in the env block of your client config, not just in your shell. MCP servers are spawned as child processes and do not inherit your interactive shell environment unless explicitly passed.

"env": {
  "CONTEXT7_API_KEY": "ctx7_live_xxxxxxxxxxxx"
}

Error: 429 Too Many Requests

Cause: You've hit the rate limit for your API key tier.

Fix (short term): Wait and retry. Fix (long term): Upgrade your Context7 plan or add retry logic in your workflow. If you're seeing this in a team, ensure everyone has their own API key rather than sharing one.

Error: spawn npx ENOENT

Cause: The AI client can't find npx because it's not in the PATH used by the spawned process.

Fix: Use the absolute path to npx:

# Find it
which npx
# Returns: /Users/you/.nvm/versions/node/v20.10.0/bin/npx

Then in your config:

"command": "/Users/you/.nvm/versions/node/v20.10.0/bin/npx"

This is the most common error on macOS with nvm-managed Node.js. GUI applications don't source your shell's .nvm setup.

Error: Tools not appearing in Claude Desktop

Checklist:

• Did you fully quit and relaunch Claude Desktop (not just close the window)?
• Is the JSON in claude_desktop_config.json valid? Test with cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool
• Does the command binary exist and is it executable?
• Is CONTEXT7_API_KEY set in the env block?
• Check Claude Desktop logs at ~/Library/Logs/Claude/ (macOS)

Error: resolve-library-id returns empty results

Cause: The library name is too specific, misspelled, or the library isn't indexed yet.

Fix: Try alternate names. @tanstack/react-query might work better than react-query. langchain-core might work better than langchain. Check context7.com to search the library index directly.

Error: fetch-library-docs returns stale content

Cause: Context7's crawl for that library may be behind schedule.

Fix: There's no way to force an immediate recrawl from the client side. File a request via Context7's support channel to prioritize a library update. For critical libraries, consider supplementing with a local documentation tool.

Node.js Version Errors

# Check current version
node --version

# If < 18, upgrade:
nvm install 20
nvm use 20
nvm alias default 20

Troubleshooting Checklist

Use this checklist before opening a GitHub issue or support ticket:

• Node.js version is 18 or higher
• API key is valid (test via curl -H "Authorization: Bearer YOUR_KEY" https://context7.com/api/health)
• npx @upstash/context7-mcp runs without error from the terminal
• Config JSON is syntactically valid
• command uses absolute path if using nvm/volta/asdf
• Client was fully restarted after config changes
• No conflicting MCP servers with the same name key
• Rate limits not exceeded (check Context7 dashboard)
• Firewall/proxy allows outbound HTTPS to context7.com

Validating Your MCP Configuration

Before relying on Context7 in a production workflow, validate that your server is behaving correctly and exposing the expected tools. MCPForge Verify provides a free compatibility check that introspects your MCP server's tool declarations, protocol version, and transport configuration — catching issues like malformed tool schemas or missing capability declarations before they surface as confusing runtime failures.

For teams managing multiple MCP servers, the MCPForge Verified Directory lists audited MCP servers with confirmed capability profiles, making it easier to find and trust community-validated integrations alongside Context7.

Security Best Practices

1. Never Hardcode API Keys in Shared Files

If .cursor/mcp.json is committed to a team repository, use environment variable references:

"env": { "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}" }

2. Rotate Keys Periodically

Context7 API keys don't expire by default but you should rotate them quarterly or immediately after any suspected exposure. Key rotation takes effect instantly — generate a new key, update all client configs, delete the old key.

3. Use Separate Keys Per Environment

Don't share a single API key across your personal machine, CI, and production. Separate keys let you audit usage per context and revoke selectively.

4. Audit What Goes to Context7

Remember: the MCP server sends libraryName and topic strings to the Context7 API. These are controlled by the LLM based on conversation context. In sensitive projects, review whether library names themselves could reveal proprietary technology choices. This is a low risk for most teams but worth acknowledging.

5. Corporate Proxy Considerations

If your organization routes all outbound traffic through a proxy, set standard Node.js proxy variables:

"env": {
  "CONTEXT7_API_KEY": "your_key",
  "HTTPS_PROXY": "http://proxy.yourcompany.com:8080",
  "NO_PROXY": "localhost,127.0.0.1"
}

6. Verify the Package Integrity

Before deploying in a team or CI context, verify the npm package checksum matches the published version:

npm view @upstash/context7-mcp dist.integrity

Performance Considerations

Startup Latency

When using npx, the first invocation after the package cache expires triggers a download. Subsequent invocations use the local cache. For users on slow connections or in air-gapped environments, use the global install approach to avoid download delays at startup.

Documentation Fetch Latency

Context7 API calls typically complete in 200–800ms depending on:

• Topic specificity (narrow topics = smaller payload = faster)
• Library documentation size
• Geographic proximity to Context7 API servers
• Current API load

This latency is incurred once per tool call. Since LLMs batch this into their reasoning loop, users typically experience it as a 1–2 second delay before the AI starts generating code — acceptable in most workflows.

Token Budget Management

The tokens parameter in fetch-library-docs directly affects both response size and your AI client's context window consumption. Large token values (10,000+) can push long conversations toward context limits faster. A practical approach:

• Default to 5,000 tokens for most queries
• Increase to 8,000–12,000 for complex APIs (React hooks, Prisma relations)
• Reserve large token budgets for dedicated documentation-lookup sessions, not ongoing coding sessions

Multiple Library Lookups

If a task requires documentation for multiple libraries, the LLM will make sequential tool calls. This compounds latency. For workflows where you know in advance which libraries you'll use, prompt the AI to fetch all documentation upfront before starting code generation.

Production Deployment Considerations

If you're deploying an agentic workflow or a team IDE environment where Context7 is used at scale, the following considerations apply. For a deeper treatment, see our guide on running MCP servers in production.

Process Management

For production agentic systems (not IDE usage), you may want the MCP server to persist rather than being spawned per-session. Consider using PM2 or systemd to keep the process alive, but be aware that the stdio transport doesn't support multiple concurrent clients — you'll need one server instance per client connection.

Centralized API Key Management

For organizations deploying Context7 to an engineering team:

• Store the API key in a secrets manager (AWS Secrets Manager, HashiCorp Vault, 1Password Secrets Automation).
• Use a startup script to inject the key into the process environment rather than storing it in any config file.

#!/bin/bash
# inject-mcp-secret.sh
export CONTEXT7_API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id context7/api-key \
  --query SecretString \
  --output text)
exec npx -y @upstash/context7-mcp

Then in your client config:

{
  "command": "/usr/local/bin/inject-mcp-secret.sh",
  "args": []
}

Health Monitoring

For agentic pipelines, instrument tool call success/failure rates. A sudden increase in fetch-library-docs returning empty results may indicate the Context7 API is experiencing issues or your key has been rate-limited.

Caching at the Application Layer

If your agentic system makes repetitive documentation requests for the same library + topic combinations, consider adding a local cache (Redis, in-memory LRU) in front of the MCP server. The Context7 documentation for a given library version is stable between crawl cycles — caching for 30–60 minutes is safe and can significantly reduce API calls.

Limitations

Being honest about limitations is more useful than marketing copy:

1. Coverage gaps: Not every library is indexed. Niche or private packages won't appear. The index is strongest for popular open-source JavaScript/TypeScript, Python, and Go libraries.

2. Crawl lag: Even for indexed libraries, there can be a delay between a new release and Context7's crawl reflecting that version. For libraries releasing frequently (weekly or faster), this is a real risk.

3. No version pinning from the client: You can't tell Context7 "give me docs for Prisma 4.x, not 5.x" directly. The API returns the most recent version it has indexed. Version selection is implicit based on what was crawled.

4. No self-hosting of the data layer: The MCP server binary is local but the documentation database is cloud-only. If Context7's API is down, the tools return errors and the LLM falls back to training data.

5. Single transport (stdio): The package doesn't support HTTP/SSE transport. You can't expose it as a remote MCP server without wrapping it in an HTTP bridge — which adds complexity.

6. No programmatic library submission: You can't add your own internal library's documentation to Context7's index through the API — this feature, if available, would require contacting Context7 directly.

Alternatives to Context7

Context7 solves a specific problem elegantly, but it's not the only option.

Context7's edge: It delivers curated, structured documentation — not raw search results. The quality of content per API call is higher than a generic search tool for well-indexed libraries.

When to prefer alternatives:

• The library you use isn't indexed by Context7 → Use Exa or GitHub MCP
• You're in an air-gapped environment → Build a local docs MCP
• You need documentation for internal proprietary libraries → Custom RAG
• You want to combine documentation with broader web research → Exa or Brave Search

Production Configuration Reference

Here's a complete, production-ready claude_desktop_config.json for a team environment that also includes a few other common MCP servers alongside Context7:

{
  "mcpServers": {
    "context7": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@upstash/context7-mcp@1.4.1"],
      "env": {
        "CONTEXT7_API_KEY": "ctx7_live_xxxxxxxxxxxxxxxxxxxx",
        "CONTEXT7_LOG_LEVEL": "warn",
        "NODE_ENV": "production"
      }
    },
    "filesystem": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/dev/projects"],
      "env": {}
    }
  }
}

Why pin the version? In team environments, @latest means different developers may run different versions depending on their npx cache state. Pinning ensures reproducible behavior across the team and makes version upgrades a deliberate, tested change.

Debugging Like a Pro

Enable Debug Logging

"env": {
  "CONTEXT7_API_KEY": "your_key",
  "CONTEXT7_LOG_LEVEL": "debug"
}

With debug logging enabled, you'll see every JSON-RPC message exchanged between the client and server, including the raw tool call parameters and API response payloads. This is essential when diagnosing issues where the AI appears to call the right tool but gets wrong results.

Test the Server Standalone

Before debugging inside an AI client, confirm the server itself works:

CONTEXT7_API_KEY=your_key CONTEXT7_LOG_LEVEL=debug npx -y @upstash/context7-mcp

In another terminal, send a raw JSON-RPC initialize message:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | CONTEXT7_API_KEY=your_key npx -y @upstash/context7-mcp

A valid response confirms the server is operational and your API key works before you involve any AI client.

Inspect Claude Desktop Logs

# macOS
tail -f ~/Library/Logs/Claude/mcp-server-context7.log

# Look for lines like:
# [ERROR] Failed to start MCP server: ...
# [INFO] Tool call: resolve-library-id
# [DEBUG] API response: 429 Too Many Requests

Key Takeaways

• Context7 MCP Server bridges the gap between AI training cutoffs and current library documentation by fetching live docs at inference time.
• It uses the MCP stdio transport — it runs locally, makes outbound HTTPS calls to Context7's cloud API, and your code never leaves your machine.
• Configuration is a single JSON block in your client's config file. The most common failure mode is npx not being in the PATH that the AI client's process uses.
• Use absolute paths to npx when your Node.js is managed by nvm, volta, or asdf.
• For teams, commit the config without API keys and use environment variable references.
• Pin the package version for team environments; use @latest only for personal experimentation.
• Validate your MCP server configuration with MCPForge Verify before relying on it in production workflows.
• Know the limitations: coverage gaps, crawl lag, no version pinning, no self-hosting. Have a fallback strategy for uncovered libraries.