Developer Guide - Context7 MCP

This guide covers how to set up the Context7 MCP server locally for development and testing.

Getting Started#

Clone the project and install dependencies:

git clone https://github.com/upstash/context7.gitcd context7pnpm i

Build:

pnpm run build

Run the server:

node packages/mcp/dist/index.js

CLI Arguments#

context7-mcp accepts the following CLI flags:

Flag	Description	Default
`--transport <stdio\|http>`	Transport to use. Use `http` for remote HTTP server or `stdio` for local integration.	`stdio`
`--port <number>`	Port to listen on when using `http` transport.	`3000`
`--api-key <key>`	API key for authentication (or set `CONTEXT7_API_KEY` env var).	-

Note

Get your API key by creating an account at context7.com/dashboard.

Examples#

HTTP transport on port 8080:

node packages/mcp/dist/index.js --transport http --port 8080

Stdio transport with API key:

node packages/mcp/dist/index.js --transport stdio --api-key YOUR_API_KEY

Environment Variables#

You can use the CONTEXT7_API_KEY environment variable instead of passing the --api-key flag. This is useful for:

Storing API keys securely in .env files
Integration with MCP server setups that use dotenv
Tools that prefer environment variable configuration

Warning

The --api-key CLI flag takes precedence over the environment variable when both are provided.

Using .env File#

# .envCONTEXT7_API_KEY=your_api_key_here

MCP Configuration with Environment Variable#

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

MCP Tools#

The server registers two tools. Both are read-only, idempotent, and open-world (annotations: readOnlyHint, idempotentHint, and openWorldHint are true; destructiveHint is false).

resolve-library-id#

Resolves a package/product name to a Context7-compatible library ID and returns matching libraries. Call this before query-docs unless the user already provides a library ID in /org/project or /org/project/version format.

Parameter	Type	Required	Description
`libraryName`	string	yes	Library name to search for and resolve to a Context7-compatible library ID. Use the official name with proper punctuation (e.g., "Next.js" not "nextjs").
`query`	string	yes	What to look up in the library's documentation, used to rank results by relevance. Sent to the Context7 API; do not include sensitive or confidential information.

query-docs#

Retrieves and queries up-to-date documentation and code examples for a library. Requires a valid library ID from resolve-library-id (or one provided directly by the user).

Parameter	Type	Required	Description
`libraryId`	string	yes	Exact Context7-compatible library ID (e.g., `/vercel/next.js` or `/vercel/next.js/v14.3.0-canary.87`).
`query`	string	yes	What to look up, scoped to a single concept. Make a separate call per concept unless the question is about how concepts interact. Do not include sensitive or confidential information.

The server declares the prompts and resources capabilities but registers no prompts and no resources — prompts/list and resources/list answer with empty collections.

Local Development Configuration#

When developing locally, use this configuration to run from source:

{  "mcpServers": {    "context7": {      "command": "npx",      "args": ["tsx", "/path/to/folder/context7/packages/mcp/src/index.ts", "--api-key", "YOUR_API_KEY"]    }  }}

Testing with MCP Inspector#

Test your setup using the MCP Inspector:

npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp

This opens an interactive inspector to verify Context7 tools are working correctly.