Pydantic AI Docs MCP server

This server provides programmatic access to the Pydantic-AI documentation through a Model Context Protocol (MCP) interface. It allows you to retrieve documentation files, list topics, access changelogs, and keep the documentation repository updated, all through standardized tool calls.

Installation

Prerequisites

• Python 3.12 or newer (recommended)
• Git

Setup Steps

1. Clone the repository:

   git clone <repository_url>
   cd pydantic-ai-docs-server
   

2. Create and activate a Python virtual environment:

   Using Python's built-in venv:

   python -m venv .venv
   source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
   

   Or using uv:

   uv venv .venv
   source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
   

3. Install dependencies:

   uv pip install -e .
   # Or using pip:
   # pip install -e .
   

Running the Server

Start the MCP server using one of these commands:

pydantic-ai-docs-server

Or:

python -m pydantic_ai_docs_server

The server will start and listen for MCP requests over standard input/output (stdio).

Available Tools

The server provides the following tools:

• update_documentation - Clones or updates the Pydantic-AI documentation repository
• get_document_by_path - Retrieves specific documentation files
• list_topics - Lists documentation files and directories
• list_available_changelogs - Lists all changelog files
• get_changelog_content - Retrieves content from specific changelog files

Using the Server

This server communicates via newline-delimited JSON messages following the Model Context Protocol (MCP).

Basic Interaction

Listing Available Tools

Send this JSON request:

{"type": "list-tools"}

Calling a Tool

Send a JSON request with the tool name and arguments:

{"type": "call-tool", "tool_name": "<tool_name>", "tool_args": {"arg1": "value1"}}

Example Tool Calls

1. Update documentation:

   {"type": "call-tool", "tool_name": "update_documentation", "tool_args": {"force_clone": false}}
   

2. Get a specific document:

   {"type": "call-tool", "tool_name": "get_document_by_path", "tool_args": {"path": "usage/models.md"}}
   

3. List documentation topics:

   {"type": "call-tool", "tool_name": "list_topics", "tool_args": {}}
   

Integration with MCP Clients

To use this server with an MCP client application like Cursor, configure it in the client's MCP settings file.

Cursor Configuration

Add the following to your .cursor/mcp.json file:

{
  "mcpServers": {
    "pydantic-ai-docs": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/pydantic-ai-docs-server",
        "run",
        "-m",
        "pydantic_ai_docs_server"
      ]
    }
  }
}

Replace /path/to/your/pydantic-ai-docs-server with the actual absolute path to the project on your system.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "pydantic-ai-docs" '{"command":"uv","args":["--directory","/path/to/your/pydantic-ai-docs-server","run","-m","pydantic_ai_docs_server"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "pydantic-ai-docs": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/your/pydantic-ai-docs-server",
                "run",
                "-m",
                "pydantic_ai_docs_server"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "pydantic-ai-docs": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/your/pydantic-ai-docs-server",
                "run",
                "-m",
                "pydantic_ai_docs_server"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect