MCP CLI Cheatsheet

Overview

MCP (Model Context Protocol) is an open protocol for connecting AI applications to external tools and data sources. MCP servers expose tools (executable functions), resources (data sources), and prompts (reusable templates). The CLI ecosystem has two main tools:

- Python SDK CLI (pip install mcp[cli]) — for building, running, and installing MCP servers - mcptools (brew install mcp or go install) — for interacting with running MCP servers

Installation & Setup

``bash # Install Python SDK with CLI pip install mcp[cli]

# Or use uv (faster) uv add mcp[cli]

# Install mcptools (Go-based client CLI) brew tap f/mcptools && brew install mcp # or: go install github.com/f/mcptools/cmd/mcptools@latest `

Quick Start

`bash # 1. Create a server file echo 'from mcp.server import MCPServer mcp = MCPServer("Demo")

@mcp.tool() def add(a: int, b: int) -> int: """Add two numbers.""" return a + b

if __name__ == "__main__": mcp.run()' > server.py

# 2. Run with Inspector uv run mcp dev server.py

# 3. Run directly via stdio uv run mcp run server.py

# 4. Install for Claude Desktop uv run mcp install server.py --name "Demo"

# 5. List available tools (mcptools) mcp tools npx -y @modelcontextprotocol/server-filesystem ~

# 6. Call a tool mcp call read_file --params '{"path":"README.md"}' npx -y @modelcontextprotocol/server-filesystem ~ `

Server Management

Run, install, and manage MCP servers:

`bash # Create an alias for frequent use mcp alias add myfs npx -y @modelcontextprotocol/server-filesystem ~/

# List all aliases mcp alias list

# Remove an alias mcp alias remove myfs

# Scan IDE/Claude configs for MCP servers mcp configs scan

# Set a server config in VS Code mcp configs set vscode my-server npm run mcp-server `

Advanced Usage

### Interactive Shell

`bash mcp shell npx -y @modelcontextprotocol/server-filesystem ~ # > tools # > call read_file --params '{"path":"README.md"}' # > format json # > /q `

### Web UI

`bash mcp web --port 8080 http://localhost:3000 `

### Scaffold a New Project

`bash mcp new tool:calculate resource:file prompt:greet `

Creates a complete TypeScript MCP project with these components pre-wired.

### Mock Server for Testing

`bash mcp mock my-server --tools 5 --resources 3 `

### Code: Python Server Skeleton

`python from mcp.server import MCPServer

mcp = MCPServer("MyApp", log_level="DEBUG")

@mcp.tool() def search_books(query: str) -> str: """Search the catalog by title or author.""" return f"Found results for {query!r}."

@mcp.resource("greeting://{name}") def greeting(name: str) -> str: """Personalized greeting.""" return f"Hello, {name}!"

if __name__ == "__main__": mcp.run() `

### Code: Python Client

`python import asyncio from mcp import Client

async def main(): async with Client(mcp) as client: # or Client("http://host:port") result = await client.call_tool("search_books", {"query": "mcp"}) print(result.structured_content)

asyncio.run(main()) `

FAQ

### How do I update MCP SDK? `bash pip install --upgrade mcp[cli] # or uv add --dev mcp[cli]@latest ` For v2 pre-releases, pin an exact version: pip install mcp[cli]==2.0.0b1.

### Why doesn't mcp run find my server object? mcp run server.py imports the file and looks for a global mcp, server, or app variable of type MCPServer. If your object has a different name, use server.py:myobject syntax. Also ensure mcp.run() is guarded by if __name__ == "__main__": — that block doesn't execute under mcp run.

### How do I debug an MCP server? - Use uv run mcp dev server.py to open the Inspector GUI - Set log_level="DEBUG" in MCPServer("Name", log_level="DEBUG") - Logs go to stderr (stdout is the MCP protocol wire — no print() statements) - Use mcp mock --tools 3 for isolated testing without real servers

### Can I use MCP with VS Code or Cursor? Yes. Most modern AI coding tools support MCP. Use the LLM app's own config (e.g., VS Code settings.json, Cursor's mcp.json) or use mcp configs set to register a server: mcp configs set cursor my-server npx ...`.