Install a local (stdio) MCP server

Local MCP servers run as a process on your machine. Your AI tool launches them, pipes data over stdin/stdout, and shuts them down when you close the session. This is the most common type of MCP server.

What is a stdio server?

A stdio MCP server is a regular command-line program. Your AI tool starts it using a command and optional args, exactly like running a program in your terminal:

npx -y @modelcontextprotocol/server-filesystem ~/Downloads

In a config file this looks like:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Downloads"]
    }
  }
}

The server runs only while your AI tool is open — it is not a persistent background process or a remote service.

Common launchers

Most local MCP servers are distributed as npm packages or Python packages. The launcher you use depends on how the server is packaged:

• npx -y @package/name — runs an npm package without installing it globally. Most JavaScript/TypeScript MCP servers.
• uvx package-name — Python equivalent of npx using uv. Python MCP servers.
• node /path/to/server.js — runs a locally cloned server directly.
• python /path/to/server.py — runs a Python server directly.
• docker run ... — servers distributed as Docker images.

Step 1 — Find the install command

Every MCP server's README includes a config snippet. It will look something like one of these:

# npx command from README
npx -y @upstash/context7-mcp

# or a full JSON snippet
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

Step 2 — Install with MCPBolt (recommended)

Open the MCPBolt menu bar app, click the paste bar at the bottom, and paste either the npx command or the full JSON snippet. MCPBolt auto-detects the format and lets you pick which tools to install it into.

npx -y @upstash/context7-mcp

MCPBolt writes the correctly formatted config to every tool you select — no JSON editing required.

Step 3 — Manual install (any tool)

Claude Desktop / Cursor / Windsurf / Gemini CLI / Roo / opencode

File: ~/Library/Application Support/Claude/claude_desktop_config.json (for Claude Desktop) or the tool-specific equivalent.

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

With environment variables:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my/mcp-server"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

Claude Code (project scope)

File: .mcp.json in your project root. Same format as Claude Desktop.

VS Code

File: .vscode/mcp.json

{
  "servers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

Zed

Add to Zed's settings.json:

{
  "context_servers": {
    "context7": {
      "command": {
        "path": "npx",
        "args": ["-y", "@upstash/context7-mcp"]
      },
      "settings": {}
    }
  }
}

Codex CLI

File: ~/.codex/config.toml

[[mcp_servers]]
name = "context7"
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Continue

File: ~/.continue/config.yaml

mcpServers:
  - name: context7
    command: "npx"
    args:
      - "-y"
      - "@upstash/context7-mcp"

Troubleshooting

• Server fails to start — Make sure the launcher is installed. Fornpx, Node.js 18+ is required. For uvx, install uv.
• Command not found — The binary (npx, node, uvx) may not be on the PATH that your AI tool sees. Specify the full path to the binary, e.g. /usr/local/bin/npx.
• Server shows amber in MCPBolt — The process started but is responding slowly. Check if the server requires env vars that are missing.
• Works in terminal but not in Claude — Claude Desktop launches with a limited PATH. Use full absolute paths for the command, or add the bin directory to your shell's PATH in ~/.zprofile or ~/.bash_profile.