# How to Run the Context7 MCP Server Locally for Development

> Learn how to run the Context7 MCP server locally for development using npx, Docker, or from source. Configure transport modes for flexible integration.

- Repository: [Upstash/context7](https://github.com/upstash/context7)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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](https://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.

```bash

# 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`.

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

```

Build and run the container:

```bash

# 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.

```bash

# 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:

```bash

# 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`](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts), the transport type resolves as:

```typescript
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`](https://github.com/upstash/context7/blob/main/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:

```bash
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:

```json
{
  "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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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.