146 Cli Commands 92e8cda1

# FastMCP CLI Commands Reference

Complete reference for FastMCP command-line interface.

## Installation

```bash
# Install FastMCP
pip install fastmcp

# or with uv
uv pip install fastmcp

# Check version
fastmcp --version
```

## Development Commands

### `fastmcp dev`

Run server with inspector interface (recommended for development).

```bash
# Basic usage
fastmcp dev server.py

# With options
fastmcp dev server.py --port 8000

# Enable debug logging
FASTMCP_LOG_LEVEL=DEBUG fastmcp dev server.py
```

**Features:**
- Interactive inspector UI
- Hot reload on file changes
- Detailed logging
- Tool/resource inspection

### `fastmcp run`

Run server normally (production-like).

```bash
# stdio transport (default)
fastmcp run server.py

# HTTP transport
fastmcp run server.py --transport http --port 8000

# SSE transport
fastmcp run server.py --transport sse
```

**Options:**
- `--transport`: `stdio`, `http`, or `sse`
- `--port`: Port number (for HTTP/SSE)
- `--host`: Host address (default: 127.0.0.1)

### `fastmcp inspect`

Inspect server without running it.

```bash
# Inspect tools and resources
fastmcp inspect server.py

# Output as JSON
fastmcp inspect server.py --json

# Show detailed information
fastmcp inspect server.py --verbose
```

**Output includes:**
- List of tools
- List of resources
- List of prompts
- Configuration details

## Installation Commands

### `fastmcp install`

Install server to Claude Desktop.

```bash
# Basic installation
fastmcp install server.py

# With custom name
fastmcp install server.py --name "My Server"

# Specify config location
fastmcp install server.py --config-path ~/.config/Claude/claude_desktop_config.json
```

**What it does:**
- Adds server to Claude Desktop configuration
- Sets up proper command and arguments
- Validates server before installing

### Claude Desktop Configuration

Manual configuration (if not using `fastmcp install`):

```json
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}
```

**Config locations:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

## Python Direct Execution

### Run with Python

```bash
# stdio (default)
python server.py

# HTTP transport
python server.py --transport http --port 8000

# With arguments
python server.py --transport http --port 8000 --host 0.0.0.0
```

### Custom Argument Parsing

```python
# server.py
if __name__ == "__main__":
    import sys

    # Parse custom arguments
    if "--test" in sys.argv:
        run_tests()
    elif "--migrate" in sys.argv:
        run_migrations()
    else:
        mcp.run()
```

## Environment Variables

### FastMCP-Specific Variables

```bash
# Logging
export FASTMCP_LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR
export FASTMCP_LOG_FILE=/path/to/log.txt

# Environment
export FASTMCP_ENV=production  # development, staging, production

# Custom variables (your server)
export API_KEY=your-key
export DATABASE_URL=postgres://...
```

### Using with Commands

```bash
# Inline environment variables
API_KEY=test fastmcp dev server.py

# From .env file
set -a && source .env && set +a && fastmcp dev server.py
```

## Testing Commands

### Run Tests with Client

```python
# test.py
import asyncio
from fastmcp import Client

async def test():
    async with Client("server.py") as client:
        tools = await client.list_tools()
        print(f"Tools: {[t.name for t in tools]}")

asyncio.run(test())
```

```bash
# Run tests
python test.py
```

### Integration Testing

```bash
# Start server in background
fastmcp run server.py --transport http --port 8000 &
SERVER_PID=$!

# Run tests
pytest tests/

# Kill server
kill $SERVER_PID
```

## Debugging Commands

### Enable Debug Logging

```bash
# Full debug output
FASTMCP_LOG_LEVEL=DEBUG fastmcp dev server.py

# Python logging
PYTHONVERBOSE=1 fastmcp dev server.py

# Trace imports
PYTHONPATH=. python -v server.py
```

### Check Python Environment

```bash
# Check Python version
python --version

# Check installed packages
pip list | grep fastmcp

# Check import paths
python -c "import sys; print('\n'.join(sys.path))"
```

### Validate Server

```bash
# Check syntax
python -m py_compile server.py

# Check imports
python -c "import server; print('OK')"

# Inspect structure
fastmcp inspect server.py --verbose
```

## Deployment Commands

### Prepare for Deployment

```bash
# Freeze dependencies
pip freeze > requirements.txt

# Clean specific to FastMCP
echo "fastmcp>=2.12.0" > requirements.txt
echo "httpx>=0.27.0" >> requirements.txt

# Test with clean environment
python -m venv test_env
source test_env/bin/activate
pip install -r requirements.txt
python server.py
```

### Git Commands for Deployment

```bash
# Prepare for cloud deployment
git add server.py requirements.txt
git commit -m "Prepare for deployment"

# Create GitHub repo
gh repo create my-mcp-server --public

# Push
git push -u origin main
```

## Performance Commands

### Profiling

```bash
# Profile with cProfile
python -m cProfile -o profile.stats server.py

# Analyze profile
python -m pstats profile.stats
```

### Memory Profiling

```bash
# Install memory_profiler
pip install memory_profiler

# Run with memory profiling
python -m memory_profiler server.py
```

## Batch Operations

### Multiple Servers

```bash
# Start multiple servers
fastmcp run server1.py --port 8000 &
fastmcp run server2.py --port 8001 &
fastmcp run server3.py --port 8002 &

# Kill all
killall -9 python
```

### Process Management

```bash
# Use screen/tmux for persistent sessions
screen -S fastmcp
fastmcp dev server.py
# Detach: Ctrl+A, D

# Reattach
screen -r fastmcp
```

## Common Command Patterns

### Local Development

```bash
# Quick iteration cycle
fastmcp dev server.py  # Edit, save, auto-reload
```

### Testing with HTTP Client

```bash
# Start HTTP server
fastmcp run server.py --transport http --port 8000

# Test with curl
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'
```

### Production-like Testing

```bash
# Set production environment
export ENVIRONMENT=production
export FASTMCP_LOG_LEVEL=WARNING

# Run
fastmcp run server.py
```

## Troubleshooting Commands

### Server Won't Start

```bash
# Check for syntax errors
python -m py_compile server.py

# Check for missing dependencies
pip check

# Verify FastMCP installation
python -c "import fastmcp; print(fastmcp.__version__)"
```

### Port Already in Use

```bash
# Find process using port
lsof -i :8000

# Kill process
lsof -ti:8000 | xargs kill -9

# Use different port
fastmcp run server.py --port 8001
```

### Permission Issues

```bash
# Make server executable
chmod +x server.py

# Fix Python path
export PYTHONPATH="${PYTHONPATH}:$(pwd)"
```

## Resources

- **FastMCP CLI Docs**: https://github.com/jlowin/fastmcp#cli
- **MCP Protocol**: https://modelcontextprotocol.io
- **Context7**: `/jlowin/fastmcp`