To run a local MCP server with Claude Code, register its launch command as a local stdio server: claude mcp add <name> [options] -- <command> [args...]. Put Claude Code options before -- and the server executable and arguments after it. Then check the connection with claude mcp list or /mcp inside Claude Code. The server runs as a local process; Claude Code still needs an internet connection for authentication and AI processing.
What “local MCP server” means in Claude Code
MCP, or Model Context Protocol, is an open-source standard for connecting AI applications to external systems such as files, databases, tools, and workflows. An MCP server exposes capabilities through that standard; Claude Code can start a local server process and communicate with it over standard input/output (stdio). The MCP introduction explains the protocol’s role.
This guide is specifically about adding a server process that runs on your machine to Claude Code. It is different from configuring a remote server by URL. It is also different from claude mcp serve, which exposes Claude Code itself as an MCP server for another client.
Before you add a server
- Install Claude Code. Use Anthropic’s current setup instructions for your operating system and installation method. Requirements and installer behavior can change, so check the instructions for the environment you actually use.
- Confirm it starts. Open a terminal in the project where you want to work and run
claude. Complete any requested sign-in. Claude Code requires internet access for its own authentication and AI processing, even if the MCP server you add runs locally. - Get the server’s launch instructions. Find its documented executable, arguments, required environment variables, and prerequisites. For example, a server may specify an
npxpackage command or auvxcommand. Use the server provider’s actual instructions rather than guessing a package name or arguments.
Add the local server from the terminal
Use Claude Code’s MCP command with this pattern:
claude mcp add <name> [options] -- <command> [args...]
Replace <name> with a short identifier you will recognize. Options before the double hyphen belong to Claude Code; the command and arguments after it are passed to the server launcher. The separator matters: without it, a flag intended for the server could be interpreted as a Claude Code option, or vice versa.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Example with a server API key
If the server’s own documentation says to start it with npx -y @example/mcp-server and read a key from the API_KEY environment variable, the registration would look like this:
claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server
This is a syntax example, not a recommendation for a particular package. Replace the package name, environment variable, and key with values specified by the server you trust. Keep real credentials private; do not put secrets in a project configuration that you intend to commit.
Choose where the configuration applies
Claude Code offers three scopes. Choose according to who should be able to use the server and where:
| Scope | Where it applies | When to choose it |
|---|---|---|
local |
Private to the current project for your user | Use for a personal setup or project-specific configuration you do not want to share. |
project |
Shared through .mcp.json at the project root |
Use when the team should share the server definition, after reviewing the command, arguments, environment, and approval implications. |
user |
Available across your projects | Use for a server you want to reuse in multiple projects. |
Specify the chosen scope with Claude Code’s --scope option before the separator, for example:
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
claude mcp add --scope user example -- npx -y @example/mcp-server
Consult the current Claude Code MCP documentation for the precise command options supported by your installed version. Where server definitions collide, Anthropic documents precedence in this order: local, then project, then user.
Verify that Claude Code can start it
A successful “Added” message confirms that Claude Code wrote a configuration; it does not by itself prove that the server process starts or is healthy. Check its reported state before relying on its tools.
- Run
claude mcp listin a terminal to inspect configured servers and their health states. - For one server’s details, run
claude mcp get <name>, substituting the identifier you added. - Alternatively, open an interactive Claude Code session and enter
/mcpto inspect MCP status and handle any approval prompt. - If a project-scoped server is pending approval, open Claude Code in the trusted workspace and review and approve it there. Do not treat a pending server as connected and usable.
Windows, WSL, and shell differences
On native Windows, Anthropic’s MCP instructions show wrapping an npx command with cmd /c, for example:
claude mcp add my-server -- cmd /c npx -y @some/package
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Use the actual package and arguments from the server’s documentation. Windows shells, paths, and command resolution differ from macOS and Linux; WSL is also a supported way to run Claude Code. Follow the setup instructions for the specific environment where Claude Code and the server will run instead of assuming a command copied from another shell will work unchanged.
Keep server configuration and credentials safe
A local stdio server is an executable process launched on your machine. Only configure a server you wrote or obtained from a provider you trust. Anthropic recommends configuring permissions for MCP servers and states that it does not audit or operate them. For a project server, inspect the shared .mcp.json command, arguments, and environment before approving it.
- Use local scope for personal, project-specific settings that should not be shared.
- Keep secrets out of committed project configuration. Use environment variables or an appropriate private scope instead.
- Review what every command and argument does, including package launchers that may download or execute code.
- Approve a project server only when you trust the workspace and understand what process it will start.
Environment-variable expansion in .mcp.json
Claude Code supports ${VAR} and ${VAR:-default} expansion in the command, arguments, environment, URL, and headers of .mcp.json configuration. If a referenced variable has no value and no default, the reference can remain unresolved and produce a warning. Set the variable in the environment Claude Code uses or supply a suitable fallback where appropriate.
Do not assume credentials automatically expand into remote server URL or header fields. Claude Code deliberately prevents certain Claude Code and provider credential variables from being forwarded there. Check Anthropic’s MCP configuration guidance for the current variable behavior and restrictions.
Troubleshoot a local MCP server
Use the status and details from claude mcp list, claude mcp get <name>, or /mcp as the starting point. Then check the likely cause:
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
| Symptom | Likely cause | What to check or do |
|---|---|---|
| The server appears in configuration but is disconnected or unhealthy. | The launch command, arguments, or required environment is wrong, or the process cannot start. | Compare the exact command and arguments with the server provider’s instructions. Confirm required programs are installed and environment variables are available to Claude Code. |
| A project server is pending approval. | The shared project configuration has not yet been trusted by the current Claude Code workspace. | Open Claude Code in the intended, trusted workspace and review the server before approving it. |
| The server starts too slowly or times out during startup. | Its initialization takes longer than Claude Code’s current startup timeout. | Anthropic documents the MCP_TIMEOUT environment variable; its example value 10000 represents ten seconds. Set a longer value only if the server needs it, and use the current documentation for the applicable configuration method. |
| A variable warning appears for a project server. | A referenced variable is missing or has no fallback. | Set the variable in the environment available to Claude Code, or use the supported ${VAR:-default} form where a default is appropriate. Avoid putting secrets in shared defaults. |
| The command works in one terminal but not in Claude Code. | The process may use a different shell, working environment, path, or operating-system command wrapper. | Check the environment that launches Claude Code and adapt the command to native Windows, WSL, macOS, or Linux as applicable. On native Windows, see the documented cmd /c wrapper for npx. |
| The server is connected but a capability is unavailable. | The server may not expose the expected tool, or its own setup and permissions may be incomplete. | Review the server’s documentation and the capabilities shown in Claude Code’s MCP status. Check its own configuration and permissions rather than assuming registration enables every possible feature. |
Or skip the browser setup
If the local MCP server you need is for website screenshots, ScreenshotNeo offers a screenshot API and MCP server for Claude, Cursor, and other MCP clients. A direct API request can return a screenshot or PDF without you managing a browser process:
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchescurl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
See the ScreenshotNeo API documentation for request options and MCP setup. Cookie banners, newsletter popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are not billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan to try it without a card.
Cost and reliability considerations
A local server may require separate software or credentials, depending on its provider; Claude Code’s registration command alone does not install or validate the server’s dependencies. Check the server provider’s setup requirements and keep its executable and environment available whenever you expect Claude Code to use it. If a local process fails, Claude Code cannot use the capabilities that process provides until it starts successfully again.
Free tools Windows power users keep installed
One-click scans. No signup required.
For a team, project scope can make configuration easier to share, but it also means each teammate should review and approve the process definition in the workspace. For a private experiment, local scope avoids sharing that configuration. User scope is useful when the same server is needed across multiple projects.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Frequently asked questions
Does a local MCP server mean Claude Code works offline?
No. The server may run locally, but Claude Code still requires an internet connection for authentication and AI processing.
Can I use a URL with the local stdio command?
The command pattern in this guide registers a local process. A URL represents a remote server configuration, which is a different transport setup; use it only when the server provider supplies a remote endpoint and follow the current Claude Code documentation.
Is “Added” proof the server is working?
No. It means the configuration was written. Check the server’s health in claude mcp list, claude mcp get <name>, or /mcp.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Should I run claude mcp serve to add a server?
No. That command serves Claude Code to another MCP client; use claude mcp add to register a third-party local server with Claude Code.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
