fastmcp-lint

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

No server execution needed — pure Python AST analysis.

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.

pip install fastmcp-lint

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.

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.

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-pytho