How to Run the Context7 MCP Server Locally for Development

You can run the Context7 MCP server locally using npx, Docker, or by building from source, with transport modes configurable via the --transport flag to switch between stdio (default) and HTTP endpoints.

The Context7 MCP server from the upstash/context7 repository enables AI assistants to retrieve up-to-date library documentation through the Model Context Protocol. Whether you are integrating with an IDE like Cursor or Claude Desktop, or building custom tooling, running the server locally requires configuring the transport layer and optionally setting an API key for higher rate limits.

Prerequisites

Before running the Context7 MCP server locally, ensure you have the following:

• Node.js 18 or higher (required for modern TypeScript features and Express server compatibility)
• Optional: Docker 20+ for containerized execution
• Optional: Context7 API key from context7.com/dashboard for increased rate limits

Local Installation Methods

You have three primary workflows for running the Context7 MCP server locally: using npx for immediate execution, Docker for isolation, or building from source for development.

Quick Start with npx (No Clone Required)

The fastest way to run the Context7 MCP server locally is via the published npm package. This requires no repository checkout and defaults to stdio transport for immediate MCP client integration.

# Run with stdio transport (default for MCP editors)

npx -y @upstash/context7-mcp --api-key YOUR_API_KEY

# Run with HTTP transport on port 3000

npx -y @upstash/context7-mcp --transport http --port 3000 --api-key YOUR_API_KEY

Docker Container Setup

For isolated environments or CI/CD pipelines, build and run the server using the provided Dockerfile located at packages/mcp/Dockerfile.

FROM node:18-alpine
WORKDIR /app
RUN npm install -g @upstash/context7-mcp
CMD ["context7-mcp"]

Build and run the container:

# Build the image from the repository root

docker build -t context7-mcp packages/mcp

# Run with stdio transport (interactive)

docker run -it --rm context7-mcp --api-key YOUR_API_KEY

# Run with HTTP transport exposed on port 3000

docker run -p 3000:3000 context7-mcp \
  --transport http --port 3000 --api-key YOUR_API_KEY

Running from Source (Development Mode)

To modify the server or debug the transport layer, clone the repository and build the TypeScript sources.

# Clone the repository

git clone https://github.com/upstash/context7.git
cd context7

# Install dependencies

pnpm install

# Build the TypeScript

pnpm build

The build output lands in packages/mcp/dist/. Run the compiled server:

# stdio mode (default)

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

# HTTP mode

node packages/mcp/dist/index.js --transport http --port 3000 --api-key YOUR_API_KEY

Configuring the Transport Layer

The Context7 MCP server supports two transport mechanisms controlled by the --transport CLI option. In packages/mcp/src/index.ts, the transport type resolves as:

const TRANSPORT_TYPE = (cliOptions.transport || "stdio") as "stdio" | "http";

stdio Transport: The default mode reads JSON-RPC messages from stdin and writes responses to stdout. This mode is required for MCP clients like Claude Desktop or Cursor that spawn the server as a subprocess.

HTTP Transport: When set to http, the server initializes an Express application with CORS middleware and listens on the port specified by --port (default 3000). This mode is useful for remote deployments or web-based integrations.

Authentication handling occurs in the extractApiKey helper function within packages/mcp/src/index.ts, which checks the --api-key CLI flag, environment variables, and HTTP headers.

Verifying Your Local Server

Test the HTTP endpoint using curl:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"fetchLibraryContext","params":{"query":"fetch"},"id":1}'

For stdio mode, verify by configuring your MCP client with the following JSON configuration:

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

Summary

• The Context7 MCP server entry point is packages/mcp/src/index.ts, which resolves the transport type from CLI options using the TRANSPORT_TYPE constant.
• You can run the server locally via npx (quickest), Docker (isolated), or from source (development).
• stdio transport is the default for MCP editor integration, while HTTP transport exposes an Express endpoint on port 3000.
• Authentication uses the --api-key flag or CONTEXT7_API_KEY environment variable, handled by the extractApiKey helper in the source.

Frequently Asked Questions

What is the default transport mode for the Context7 MCP server?

The default transport mode is stdio (standard input/output). In packages/mcp/src/index.ts, the transport type defaults to "stdio" when no --transport CLI argument is provided, making it compatible with MCP clients that spawn the server as a subprocess.

Do I need an API key to run the server locally?

No, an API key is optional for basic functionality, but recommended for higher rate limits. You can provide the key via the --api-key CLI flag or set the CONTEXT7_API_KEY environment variable. The extractApiKey function in packages/mcp/src/index.ts handles authentication by checking headers and environment variables.

How do I switch between stdio and HTTP transport modes?

Use the --transport CLI option followed by either stdio or http. For HTTP mode, you can also specify the port with --port (default is 3000). For example: node packages/mcp/dist/index.js --transport http --port 8080. This configuration is parsed in the main entry point of the server.

Which Node.js version is required for local development?

Node.js 18 or higher is required. This version requirement ensures compatibility with the modern TypeScript features and the Express server implementation used in the HTTP transport mode. The Docker image also uses node:18-alpine as its base image for consistency.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}