Developer Guide

Set up and run Context7 MCP locally for development

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.git
cd context7
pnpm 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. 0 picks a free port.	3000
--api-key <key>	API key for authentication (or set CONTEXT7_API_KEY env var).	-

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

HTTP transport requires a credential on every request by default. Clients send Authorization: Bearer YOUR_API_KEY. Set MCP_AUTH_ENFORCEMENT=observe to also accept requests without credentials on /mcp.

Opaque OAuth access tokens (oat_…) are checked against the Context7 API before each request is served (one check per token per minute on each replica; the cache is in memory, and a rejected token stays rejected for ten minutes). An expired or revoked token gets an HTTP 401 with a WWW-Authenticate challenge so MCP clients refresh it. Set MCP_OAUTH_TOKEN_VALIDATION=off to skip that check and forward the token unchecked.

OAuth JWT access tokens from the authorization server (OAUTH_AUTH_SERVER_URL) are verified locally: signature against its JWKS, issuer, a typ of at+jwt, and expiry with a minute of clock tolerance. Clerk ID tokens and session JWTs share that issuer but are not access tokens, so they are always rejected. The token’s aud must name this server (RESOURCE_URL origin, /mcp, or /mcp/oauth; override with a comma-separated MCP_OAUTH_ALLOWED_AUDIENCES). The query string of an audience on an allowed host is ignored. MCP_OAUTH_AUDIENCE_ENFORCEMENT sets what a mismatch does: observe (default) admits a token with a missing or foreign audience; foreign answers HTTP 401 to a token issued for another server and still admits one with no aud; required answers 401 to both. Every mismatch is logged with the OAuth client ID, the audience and the outcome, once per token per hour on each replica.

The HTTP server is stateless — it creates a fresh server instance per request and keeps no session state. Session operations therefore have nothing to attach to: a GET or DELETE on /mcp is answered with 405 Method Not Allowed rather than opening a standalone Server-Sent Events stream. Server-Sent Events are used only to stream responses to POST requests, and keepalive heartbeats are disabled.

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

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

​

Using .env File

# .env
CONTEXT7_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"
      }
    }
  }
}

​

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.