Skip to content
Get packs

Guide · Agent skill

How to use the Build a Bundled Local MCP Server agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The build-mcpb skill is an instruction set that tells an AI agent how to package a local MCP server, meaning one that reads local files, drives a desktop app or uses OS features, into a single .mcpb file. This guide is for developers who want non-technical users to install such a server without setting up Node, Python or other tools. After reading it you will know how to install the skill, how to ask for it in plain language, and what safety steps the agent should cover.

Build a Bundled Local MCP Serveranthropics/claude-plugins-official · Apache-2.0

Quick start

  1. 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Describe your local server. Tell the agent what the server must access on the user's machine, such as a folder, a desktop app or OS features.
  3. 3Let the agent write the manifest. The agent creates manifest.json with the server entry point, mcp_config command and any user_config settings.
  4. 4Secure the tool handlers. Ask the agent to validate every path against the root and allowlist any spawned process, since MCPB has no sandbox.
  5. 5Build the bundle. Run the Node or Python build steps the agent gives you, then pack the directory with npx @anthropic-ai/mcpb pack.
  6. 6Validate and test. Run the validate command and test the server with the MCP inspector on a machine without your dev tools.

What the build-mcpb skill makes the agent do

An agent skill is a folder with a SKILL.md file and optional reference files. When your request matches the skill's description, the agent reads those instructions and follows them while it works on your project.

This skill covers packaging a local MCP server with its runtime. The source describes an MCPB bundle as a zip archive containing a manifest.json, your server code under server/, and an icon. The agent is guided through writing the manifest, building the server for Node or Python, and running the pack command.

  • Lays out the bundle structure: manifest.json, server/ and icon.png
  • Explains the manifest.json format, including server.mcp_config and user_config
  • Provides a sample file-access server with list_files and read_file tools
  • Gives build steps for Node (esbuild and mcpb pack) and Python (pip install into a vendor folder)
  • Includes security guidance for path validation, since MCPB has no sandbox

Install the build-mcpb skill

Download the ZIP for this skill from this page and unzip it. You can put it in one of two places, depending on how you want to use it.

For a personal setup, unzip it into ~/.claude/skills/. To use it only in one project, unzip it into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Single project: your project's .claude/skills/ folder
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Trigger the skill with natural requests

You do not need to type a special command. The skill's description lists phrases that should activate it, so ordinary requests work. Mention what you are building and who will install it.

The skill is most useful when your server must run on the user's machine. The source says that if your server only calls cloud APIs, a remote HTTP server is usually the better choice, and the agent may point you there instead.

  • "Package this local MCP server as an MCPB so non-technical users can install it."
  • "Bundle my MCP server with its Node runtime. It needs to read files on the user's computer."
  • "Make an MCPB that controls our desktop app and must install without Node set up."
  • "I have a Python MCP server that reads local folders. Help me ship it as a .mcpb file."

Example: packaging a local file server

A typical session starts with a server that exposes a folder. The skill's sample uses a ROOT_DIR environment variable, set from a user_config directory picker in the manifest, so the user chooses the folder during install. The sample server registers list_files and read_file tools, both marked read-only.

After the agent writes the code, the Node build flow in the source is: npm install, bundle with esbuild into server/index.js, then pack the directory with the MCPB tool. Before you share the file, the source recommends testing it on a machine without your developer tools.

  • Ask the agent to add a tool and it will update the handler and keep path checks in place
  • Ask it to validate the manifest before packing
npx @anthropic-ai/mcpb validate npx @anthropic-ai/mcpb pack

What you need before you start

The skill needs Node.js and npm for the esbuild and @anthropic-ai/mcpb pack commands. Python and pip are needed only if your server is in Python. The example server code uses MCP SDK packages such as @modelcontextprotocol/sdk and zod.

The skill runs scripts and does not use the network itself, according to the source. Your own server may make network calls, so review its code as you would any other program.

  • Node.js and npm for the Node build path
  • Python and pip only for Python servers
  • @modelcontextprotocol/sdk and zod for the example code

Safety notes: MCPB has no sandbox

MCPB does not enforce permissions. The manifest has no permissions block, so the server runs with the user's full privileges and can read any file the user can. The source says tool inputs should be treated as untrusted, because an AI can be tricked by content it reads.

Your tool handlers are the only protection. The skill's reference on local security says to resolve each user path against the root, check that it stays inside, and allowlist any process you spawn. Do not expect the manifest to limit file or network access.

  • Validate every path and refuse anything that escapes the root directory
  • Allowlist any process your server launches
  • Do not rely on the manifest to restrict access
  • If the host supports roots/list, the skill suggests using it to get user-approved directories

Tips for better results

Give the agent the facts it needs: what the server must touch on the user's machine, which runtime you use, and whether it talks to a desktop app or only to files. Clear inputs lead to a smaller and safer bundle.

Avoid native dependencies where you can. The source notes that native extensions such as numpy must be built for each target platform, which complicates Python bundles.

  • Name the local resource the server needs (folder, app, OS feature)
  • Prefer pure-JavaScript or pure-Python dependencies
  • Ask for a manifest validation step before packing
  • Test the .mcpb on a clean machine before distributing

What people use it for

  • Packaging a local file browser so a non-technical user can pick a folder during install and let Claude search its documents
  • Shipping a server that drives a desktop application through OS-level APIs
  • Distributing a local helper that talks to a localhost service without asking users to install Node or Python
  • Deciding, with the skill's guidance, whether a cloud-only tool should be a remote MCP server instead

Frequently asked questions

Is the build-mcpb skill free?

The source file is licensed under Apache-2.0, which is stated on this page. Check the licence file in the repository for the full terms before you reuse or redistribute it.

What do I need installed to use it?

You need Node.js and npm for the esbuild and mcpb pack commands. Python and pip are needed only if you are building a Python server. The example code also uses MCP SDK packages such as @modelcontextprotocol/sdk and zod.

Where do I put the skill files?

Unzip the downloaded ZIP into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

Does the skill run scripts or use the network?

The source says the skill runs scripts and does not use the network itself. The code it helps you write may still make network calls, so review that code carefully.

Does the manifest restrict what my server can access?

No. MCPB has no permissions system, so the server runs with full user privileges. You must validate paths and restrict spawns in your own code.

When should I use a remote MCP server instead?

If your server only calls cloud APIs, the source recommends a remote HTTP server. Local packaging adds security work and gives no benefit when the server does not need the user's machine.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are building a local MCP server that reads files or controls apps on a user's computer and you want people to install a single file without setting up Node or Python. Pick a remote HTTP MCP server instead if your tool only calls cloud APIs, or if you are not prepared to write and review path-checking code, because MCPB gives you no sandbox.

Download the skill