pydantic-mcp is an MCP server for inspecting, validating, and working with Pydantic models and Python type contracts in LLM workflows, providing deterministic validation, serialization, schema generation, and migration assistance.
Discover Models: Scan configured packages to find exported Pydantic BaseModel classes, with optional filtering and package selection.
Inspect & Explain Types: Resolve any Python type annotation or model into a structured description, and generate human-readable documentation covering fields, defaults, aliases, constraints, and nested structures.
Validate Data: Validate arbitrary payloads against a model or Python type expression, with support for strict mode, Python/JSON mode, and validation context.
Serialize Data: Dump validated data using Pydantic serialization, with options for aliases, excluding unset/none/default values, round-trip mode, and Python/JSON output.
Generate JSON Schema: Produce validation or serialization JSON Schema for any model or type, with optional $defs definitions.
Create Example Payloads: Generate valid (and optionally invalid) example payloads for a target model or type.
Compare Validation Modes: Contrast model vs. TypeAdapter, strict vs. non-strict, and Python vs. JSON validation behavior for the same data.
Migrate v1 to v2: Analyze code snippets or model sources for common Pydantic v1-to-v2 migration issues, with optional auto-fix suggestions.
Parse Partial JSON: Best-effort parse incomplete JSON strings and validate the resulting fragment against a target type.
Generate Model from JSON: Infer and generate candidate Pydantic model definitions from a sample JSON payload.
MCP Integration: Expose tools, resources, and prompts via the MCP protocol, with HTTP health and readiness endpoints for server monitoring.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pydantic-mcp Generate a JSON schema for the UserProfile model"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pydantic-mcp is an MCP server for inspecting Pydantic models and Python type contracts. It is built for LLM workflows that need deterministic validation, serialization, schema generation, model explanations, and migration help.
Discover Pydantic BaseModel classes across configured packages.
Resolve targets from import paths, short model names, Python type expressions, or inline model snippets.
Validate arbitrary payloads with TypeAdapter or model behavior.
Serialize validated data in Python or JSON mode.
Generate validation and serialization JSON Schema.
Explain fields, defaults, aliases, decorators, constraints, and nested models.
Generate valid and invalid example payloads.
Infer candidate Pydantic models from sample JSON payloads.
Compare strict/non-strict and Python-vs-JSON validation behavior.
Analyze common Pydantic v1 to v2 migration issues.
Parse partial JSON with pydantic_core.from_json.
Expose MCP tools, resources, prompts, plus HTTP health/readiness routes.
Related MCP server: openapi-mcp-proxy
list_models
inspect_type
explain_model
validate_data
serialize_data
generate_json_schema
create_example_payload
generate_model_from_json
compare_validation_modes
migrate_v1_to_v2
parse_partial_json
pydantic://server/capabilities
pydantic://project/settings
pydantic://project/import-roots
pydantic://project/errors/recent
pydantic://project/models/changed
pydantic://models/index
pydantic://models/{qualified_name}
pydantic://schemas/{qualified_name}?mode=validation|serialization
pydantic://examples/{qualified_name}
pydantic://migration/rules
pydantic://reference/overview
explain model
generate api contract docs
debug validation error
design a model from example json
review schema compatibility
migrate to pydantic v2
Install dependencies:
uv syncRun over stdio:
uv run python mcp_server.py --transport stdioRun over HTTP:
uv run python mcp_server.py --transport http --host 127.0.0.1 --port 8000Health endpoints:
GET /healthz
GET /readyz
Important environment variables:
PYDANTIC_MCP_ALLOWED_IMPORT_ROOTS
PYDANTIC_MCP_DEFAULT_SCAN_PACKAGES
PYDANTIC_MCP_IMPORT_TIMEOUT_SECONDS
PYDANTIC_MCP_ERROR_HISTORY_LIMIT
PYDANTIC_MCP_TRANSPORT
PYDANTIC_MCP_HOST
PYDANTIC_MCP_PORT
Example:
PYDANTIC_MCP_ALLOWED_IMPORT_ROOTS=your_app.models \
PYDANTIC_MCP_DEFAULT_SCAN_PACKAGES=your_app.models \
uv run python mcp_server.py --transport stdioThese values must point at importable application packages in the runtime environment. For local smoke tests, the repository ships an installable sample package at pydantic_mcp_sample_app, but production deployments should point at your own application modules.
just testCompare model, TypeAdapter, strict, and JSON-vs-Python validation behavior.
Inputs: target (required), data (required). Returns: result, artifacts, diagnostics, resolved_target
Generate example valid and invalid payloads for a target model or type.
Inputs: target (required), count, invalid_examples. Returns: result, artifacts, diagnostics, resolved_target
Turn a model or type into a human-readable contract.
Inputs: target (required), include_examples, include_constraints, include_defaults. Returns: result, artifacts, diagnostics, resolved_target
Generate JSON Schema for a model or type.
Inputs: target (required), schema_mode, include_definitions. Returns: result, artifacts, diagnostics, resolved_target
Infer candidate Pydantic models from a JSON string or JSON-like payload.
Inputs: json_input (required), model_name. Returns: result, artifacts, diagnostics, resolved_target
Resolve a Python type annotation or model into a structured description.
Inputs: target (required), expand_nested. Returns: result, artifacts, diagnostics, resolved_target
Discover exported Pydantic models in configured packages.
Inputs: packages, filter. Returns: result, artifacts, diagnostics, resolved_target
Analyze a snippet or model source for common Pydantic v1-to-v2 migration issues.
Inputs: code, target, apply_fixes. Returns: result, artifacts, diagnostics, resolved_target
Best-effort parse partial JSON, then validate the parsed fragment.
Inputs: target (required), partial_json (required), allow_partial. Returns: result, artifacts, diagnostics, resolved_target
Dump validated data using Pydantic serialization behavior.
Inputs: target (required), data (required), output_mode, by_alias, +4 more. Returns: result, artifacts, diagnostics, resolved_target
Validate input against a model name or Python type expression.
Inputs: target (required), data (required), mode, strict, +1 more. Returns: result, artifacts, diagnostics, resolved_target
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 11 tools
Each tool has a clearly distinct purpose with no overlap: compare_validation_modes analyzes validation behavior differences, create_example_payload generates test data, explain_model creates human-readable documentation, generate_json_schema produces JSON Schema, generate_model_from_json infers models from JSON, inspect_type resolves type annotations, list_models discovers available models, migrate_v1_to_v2 handles version migration, parse_partial_json processes incomplete JSON, serialize_data handles data serialization, and validate_data performs validation. The descriptions clearly differentiate their specific functions.
The naming follows a consistent verb_noun pattern throughout (e.g., compare_validation_modes, create_example_payload, explain_model) with all tools using snake_case. The only minor deviation is that 'list_models' uses a plural noun while others typically use singular nouns (e.g., 'explain_model'), but this is a small inconsistency that doesn't affect readability or predictability.
With 11 tools, this is well-scoped for a Pydantic-focused server. Each tool serves a distinct purpose in the Pydantic ecosystem (validation, schema generation, migration, serialization, etc.), and none feel redundant or unnecessary. The count aligns perfectly with providing comprehensive coverage for working with Pydantic models and validation.
The tool surface provides complete coverage for Pydantic operations: it includes model discovery (list_models), type inspection (inspect_type), schema generation (generate_json_schema), validation (validate_data, compare_validation_modes), serialization (serialize_data), migration support (migrate_v1_to_v2), example generation (create_example_payload), documentation (explain_model), and even specialized utilities like parsing partial JSON (parse_partial_json) and model inference (generate_model_from_json). No obvious gaps exist for typical Pydantic workflows.
MCP Spec Compliance MCP — audits any MCP server.json against the official Model Context Protocol
Monitor MCP servers, API contracts and AI outputs for schema drift. Alerts on breaking changes.
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
