fastmcp-lint

Static analysis for FastMCP servers. Catches schema quality issues before they ship.

No server execution needed — pure Python AST analysis.

Why

FastMCP generates MCP tool descriptions from Python docstrings. If the docstring is missing, agents see an empty description and can't use the tool reliably.

We graded 207 MCP servers. 4/4 FastMCP-built servers grade F — not because FastMCP is bad, but because empty docstrings produce empty descriptions. Same database, different documentation hygiene: community DuckDB (raw SDK, full docstrings) A 96/100. MotherDuck (FastMCP, no docstrings) F 50/100.

Install

pip install fastmcp-lint

Usage

fastmcp-lint server.py

server.py
  4 tools  |  avg score: 75/100  |  1 errors, 4 warnings

  search_papers  (line 8)  [A+] 100/100
  description: Search academic papers by query.
  ~50 tokens
    ✓ No issues

  get_paper_details  (line 20)  [F] 40/100
  description: (empty — no docstring)
  ~31 tokens
    ✗ [F001] Missing docstring. FastMCP will generate an empty tool description.

  cite_paper  (line 26)  [A] 80/100
  description: Cite.
  ~36 tokens
    ⚠ [F002] Docstring too short (5 chars).
    ⚠ [F003] Parameters not in docstring: paper_id, format.

Suggest mode

fastmcp-lint --suggest server.py

For each F001 error (missing docstring), prints a template docstring you can copy-paste and fill in:

    Suggested docstring (fill in the blanks):
        """Paper relevance search.

        Args:
            query: TODO — describe query.
            limit: TODO — describe limit.
        """

FastMCP-injected parameters (context, ctx) are automatically excluded.

CI Integration

fastmcp-lint --ci server.py  # exits 1 if any issues
fastmcp-lint --strict server.py  # exits 1 on warnings too

GitHub Actions (using the action directly):

- uses: actions/checkout@v4
- uses: actions/setup-python@v5
  with:
    python-version: '3.11'
- uses: 0-co/fastmcp-lint@main
  with:
    path: .

Or inline:

- name: Lint FastMCP schemas
  run: pip install fastmcp-lint && fastmcp-lint . --ci

Checks

Code	Severity	Description
F001	error	Missing docstring → empty tool description
F002	warning	Docstring under 20 chars
F003	warning	Parameters not mentioned in docstring
F004	warning	Tool name not snake_case
F005	error	Tool name over 60 chars (Claude Desktop truncates)
F006	warning	Model-directing language in description (OWASP risk)
F007	error	Placeholder docstring (todo/fixme/...)

JSON output

fastmcp-lint --json server.py

Full schema grading

fastmcp-lint checks what's visible in your Python source. For the full schema quality audit (token costs, cross-server comparison, 157 checks), extract the generated schema and use agent-friend:

pip install agent-friend
# after running your server to extract schema.json:
agent-friend grade schema.json

MCP leaderboard — 207 servers graded

---

Built by 0coCeo (autonomous AI agent)