fastmcp
Build, test, inspect, install, and deploy MCP servers with FastMCP in Python. Use when creating a new MCP server, wrapping an API or database as MCP tools, exposing resources or prompts, or preparing a FastMCP server for Claude Code, Cursor, or HTTP deployment.
- License 许可
- MIT
- 最近更新
- 2026-08-31
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- fastmcp
- author
- Hermes Agent
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "MCP", "FastMCP", "Python", "Tools", "Resources", "Prompts", "Deployment" ], "homepage": "https://gofastmcp.com", "related_skills": [ "native-mcp", "mcporter" ] } }
- platforms
- [ "linux", "macos", "windows" ]
- description
- Build, test, inspect, install, and deploy MCP servers with FastMCP in Python. Use when creating a new MCP server, wrapping an API or database as MCP tools, exposing resources or prompts, or preparing a FastMCP server for Claude Code, Cursor, or HTTP deployment.
- prerequisites
- { "commands": [ "python3" ] }
02 资源文件 5
- 参考文档references/fastmcp-cli.md2.3 KB
- 脚本scripts/scaffold_fastmcp.py2.0 KB
- 脚本templates/api_wrapper.py1.6 KB
- 脚本templates/database_server.py2.2 KB
- 脚本templates/file_processor.py1.6 KB
03 SKILL.md 正文
FastMCP
Build MCP servers in Python with FastMCP, validate them locally, install them into MCP clients, and deploy them as HTTP endpoints.
When to Use
Use this skill when the task is to:
- create a new MCP server in Python
- wrap an API, database, CLI, or file-processing workflow as MCP tools
- expose resources or prompts in addition to tools
- smoke-test a server with the FastMCP CLI before wiring it into Hermes or another client
- install a server into Claude Code, Claude Desktop, Cursor, or a similar MCP client
- prepare a FastMCP server repo for HTTP deployment
Use native-mcp when the server already exists and only needs to be connected to Hermes. Use mcporter when the goal is ad-hoc CLI access to an existing MCP server instead of building one.
Prerequisites
Install FastMCP in the working environment first:
pip install fastmcp
fastmcp version
For the API template, install httpx if it is not already present:
pip install httpx
Included Files
Templates
templates/api_wrapper.py- REST API wrapper with auth header supporttemplates/database_server.py- read-only SQLite query servertemplates/file_processor.py- text-file inspection and search server
Scripts
scripts/scaffold_fastmcp.py- copy a starter template and replace the server name placeholder
References
references/fastmcp-cli.md- FastMCP CLI workflow, installation targets, and deployment checks
Workflow
1. Pick the Smallest Viable Server Shape
Choose the narrowest useful surface area first:
- API wrapper: start with 1-3 high-value endpoints, not the whole API
- database server: expose read-only introspection and a constrained query path
- file processor: expose deterministic operations with explicit path arguments
- prompts/resources: add only when the client needs reusable prompt templates or discoverable documents
Prefer a thin server with good names, docstrings, and schemas over a large server with vague tools.
2. Scaffold from a Template
Copy a template directly or use the scaffold helper:
python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py \
--template api_wrapper \
--name "Acme API" \
--output ./acme_server.py
Available templates:
python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py --list
If copying manually, replace __SERVER_NAME__ with a real server name.
3. Implement Tools First
Start with @mcp.tool functions before adding resources or prompts.
Rules for tool design:
- Give every tool a concrete verb-based name
- Write docstrings as user-facing tool descriptions
- Keep parameters explicit and typed
- Return structured JSON-safe data where possible
- Validate unsafe inputs early
- Prefer read-only behavior by default for first versions
Good tool examples:
get_customersearch_ticketsdescribe_tablesummarize_text_file
Weak tool examples:
runprocessdo_thing
4. Add Resources and Prompts Only When They Help
Add @mcp.resource when the client benefits from fetching stable read-only content such as schemas, policy docs, or generated reports.
Add @mcp.prompt when the server should provide a reusable prompt template for a known workflow.
Do not turn every document into a prompt. Prefer:
- tools for actions
- resources for data/document retrieval
- prompts for reusable LLM instructions
5. Test the Server Before Integrating It Anywhere
Use the FastMCP CLI for local validation:
fastmcp inspect acme_server.py:mcp
fastmcp list acme_server.py --json
fastmcp call acme_server.py search_resources query=router limit=5 --json
For fast iterative debugging, run the server locally:
fastmcp run acme_server.py:mcp
To test HTTP transport locally:
fastmcp run acme_server.py:mcp --transport http --host 127.0.0.1 --port 8000
fastmcp list http://127.0.0.1:8000/mcp --json
fastmcp call http://127.0.0.1:8000/mcp search_resources query=router --json
Always run at least one real fastmcp call against each new tool before claiming the server works.
6. Install into a Client When Local Validation Passes
FastMCP can register the server with supported MCP clients:
fastmcp install claude-code acme_server.py
fastmcp install claude-desktop acme_server.py
fastmcp install cursor acme_server.py -e .
Use fastmcp discover to inspect named MCP servers already configured on the machine.
When the goal is Hermes integration, either:
- configure the server in
~/.hermes/config.yamlusing thenative-mcpskill, or - keep using FastMCP CLI commands during development until the interface stabilizes
7. Deploy After the Local Contract Is Stable
For managed hosting, Prefect Horizon is the path FastMCP documents most directly. Before deployment:
fastmcp inspect acme_server.py:mcp
Make sure the repo contains:
- a Python file with the FastMCP server object
requirements.txtorpyproject.toml- any environment-variable documentation needed for deployment
For generic HTTP hosting, validate the HTTP transport locally first, then deploy on any Python-compatible platform that can expose the server port.
Common Patterns
API Wrapper Pattern
Use when exposing a REST or HTTP API as MCP tools.
Recommended first slice:
- one read path
- one list/search path
- optional health check
Implementation notes:
- keep auth in environment variables, not hardcoded
- centralize request logic in one helper
- surface API errors with concise context
- normalize inconsistent upstream payloads before returning them
Start from templates/api_wrapper.py.
Database Pattern
Use when exposing safe query and inspection capabilities.
Recommended first slice:
list_tablesdescribe_table- one constrained read query tool
Implementation notes:
- default to read-only DB access
- reject non-
SELECTSQL in early versions - limit row counts
- return rows plus column names
Start from templates/database_server.py.
File Processor Pattern
Use when the server needs to inspect or transform files on demand.
Recommended first slice:
- summarize file contents
- search within files
- extract deterministic metadata
Implementation notes:
- accept explicit file paths
- check for missing files and encoding failures
- cap previews and result counts
- avoid shelling out unless a specific external tool is required
Start from templates/file_processor.py.
Quality Bar
Before handing off a FastMCP server, verify all of the following:
- server imports cleanly
fastmcp inspect <file.py:mcp>succeedsfastmcp list <server spec> --jsonsucceeds- every new tool has at least one real
fastmcp call - environment variables are documented
- the tool surface is small enough to understand without guesswork
Troubleshooting
FastMCP command missing
Install the package in the active environment:
pip install fastmcp
fastmcp version
fastmcp inspect fails
Check that:
- the file imports without side effects that crash
- the FastMCP instance is named correctly in
<file.py:object> - optional dependencies from the template are installed
Tool works in Python but not through CLI
Run:
fastmcp list server.py --json
fastmcp call server.py your_tool_name --json
This usually exposes naming mismatches, missing required arguments, or non-serializable return values.
Hermes cannot see the deployed server
The server-building part may be correct while the Hermes config is not. Load the native-mcp skill and configure the server in ~/.hermes/config.yaml, then restart Hermes.
References
For CLI details, install targets, and deployment checks, read references/fastmcp-cli.md.
04 同仓库更多 Skills
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations.
openai-docs
Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.
skill-creator-cc
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
prd-writing-guide
Write complete, unambiguous PRDs that development teams can implement without guesswork. Includes requirement discovery framework, structured documentation methodology, completeness checklists, and common pitfall avoidance. Use when: writing new PRDs, reviewing PRD drafts, validating requirement completeness, preparing for engineering handoff. Triggers: 'write PRD', '写PRD', '产品需求文档', '需求文档', '需求规格', '需求评审', '完善需求', 'create requirements doc', 'product requirements', 'feature spec', 'requirements document'. Anti-triggers: 'technical design doc', 'architecture design', 'implementation plan', 'API design', '架构设计', '技术方案', '实现方案', '接口设计'.