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

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)