zhongwei/gh-jezweb-claude-skills-skills-fastmcp

Fork 0

Files

Zhongwei Li 99a553f8ab Initial commit

2025-11-30 08:24:49 +08:00

7.0 KiB

Raw Blame History

FastMCP CLI Commands Reference

Complete reference for FastMCP command-line interface.

Installation

# 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).

# 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).

# 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.

# 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.

# 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):

{
  "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

# 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

# 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

# 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

# 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

# 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())

# Run tests
python test.py

Integration Testing

# 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

# 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

# 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

# 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

# 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

# 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

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

# Analyze profile
python -m pstats profile.stats

Memory Profiling

# Install memory_profiler
pip install memory_profiler

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

Batch Operations

Multiple Servers

# 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

# 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

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

Testing with HTTP Client

# 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

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

# Run
fastmcp run server.py

Troubleshooting Commands

Server Won't Start

# 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

# 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

# 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

7.0 KiB Raw Blame History