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

```bash
git clone https://github.com/upstash/context7.git
cd context7
pnpm i
```

Build:

```bash
pnpm run build
```

Run the server:

```bash
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](https://context7.com/dashboard).
</Note>

### Examples

HTTP transport on port 8080:

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

Stdio transport with API key:

```bash
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.
</Warning>

### Using .env File

```bash
# .env
CONTEXT7_API_KEY=your_api_key_here
CONTEXT7_API_URL=https://context7.com/api
```

`CONTEXT7_API_URL` sets the base URL for Context7 API calls and defaults to `https://context7.com/api`.
Override it for self-hosted deployments or proxies that sit in front of the API.

### MCP Configuration with Environment Variable

```json
{
  "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:

```json
{
  "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:

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

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