gravix-db/docketbird-mcp

DocketBird MCP Server

This MCP server provides access to DocketBird's court case data and document management functionality.

Requirements

• Python 3.11
• uv package manager

Setup

1. Install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create and activate a virtual environment:

uv venv
source .venv/bin/activate  # On Unix/MacOS
# OR
.venv\Scripts\activate     # On Windows

3. Install dependencies:

uv pip install .

4. Set up your environment variables:

export DOCKETBIRD_API_KEY=your_api_key_here  # On Unix/MacOS
# OR
set DOCKETBIRD_API_KEY=your_api_key_here     # On Windows

Running the Server

Run the server using:

uv run docketbird_mcp.py --transport stdio  # For stdio transport
uv run docketbird_mcp.py --transport sse    # For SSE transport

Available Tools

The server provides the following tools:

1. get_case_details: Get comprehensive details about a case including all documents
2. download_document_by_id: Download a specific document by its DocketBird ID
3. list_cases: Get a list of cases belonging to an account
4. list_courts_and_types: Get a comprehensive list of all available courts and case types

Configuration Files

Make sure these files are in the same directory as the script:

• courts.json: Contains information about all available courts
• case_types.json: Contains information about different types of cases

MCP Server Configuration

The MCP server configuration can be added to one of these locations depending on your MCP client:

• Cursor: ~/.cursor/mcp.json
• Claude in mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• How to open Claude Desktop config file from app
  • Launch Claude Desktop application
  • Navigate to the application menu and select Settings
  • Select Developer from the left navigation panel
  • Click the Edit Config button
  • Your system will automatically open the configuration file in your default text editor

1. Install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

Add the following configuration to the appropriate file:

For macOS:

{
  "mcpServers": {
    "docketbird-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "PATH_TO_THE_SERVER/docketbird-mcp",
        "python",
        "docketbird_mcp.py"
      ],
      "env": {
        "DOCKETBIRD_API_KEY": "YOUR_KEY"
      }
    }
  }
}

For Windows:

{
  "mcpServers": {
    "docketbird-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "PATH_TO_SERVER\\docketbird-mcp",
        "python",
        "docketbird_mcp.py"
      ],
      "env": {
        "DOCKETBIRD_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Be sure to replace:

• PATH_TO_THE_SERVER with the actual path to where you cloned the DocketBird MCP repository (for macOS)
• PATH_TO_SERVER with the actual path to where you cloned the DocketBird MCP repository (for Windows)
• YOUR_KEY with your actual DocketBird API key

Deployment

The DocketBird MCP server can be deployed to a cloud server using Docker and GitHub Actions. The deployment process is defined in the .github/workflows/deploy.yml file.

Docker Deployment

The server is containerized using Docker. You can build and run the Docker image locally with the desired transport type:

# Build for ARM architecture (M1/M2 Mac)
docker buildx build --platform linux/arm64 -t docketbird-mcp-arm:latest --load .

# Build for AMD architecture (standard servers)
docker buildx build --platform linux/amd64 -t docketbird-mcp:latest --load .

# Run locally with stdio transport
docker run -d \
  --name docketbird-mcp-stdio \
  --restart=always \
  -e DOCKETBIRD_API_KEY="your_api_key_here" \
  -e TRANSPORT_TYPE="stdio" \
  docketbird-mcp-arm:latest /app/start.sh

# Run locally with SSE transport
docker run -d \
  --name docketbird-mcp-sse \
  --restart=always \
  -e DOCKETBIRD_API_KEY="your_api_key_here" \
  -e TRANSPORT_TYPE="sse" \
  docketbird-mcp-arm:latest /app/start.sh

Validating Deployment

To validate that your deployment is working correctly:

1. Check that the container is running:

docker ps | grep docketbird-mcp

2. Verify the container logs:

docker logs docketbird-mcp

The logs should show:

Starting DocketBird MCP server...
API Key set: your_...
Running python docketbird_mcp.py

3. Test the connection from your MCP client using the configuration from this README.

If the container isn't running, you can troubleshoot by checking:

• Docker image exists: docker images | grep docketbird
• Container logs for errors: docker logs docketbird-mcp
• Server logs: Check if there are any permission or network issues

DocketBird Agent Prototype

A prototype agent has been created to interact with the deployed DocketBird MCP server. This agent provides a user-friendly interface for querying case information and document details.

Features

• Interactive command-line interface
• Natural language querying for case information
• Connects to the deployed DocketBird MCP server

Setup and Running

1. Ensure you have the OpenAI API key set as an environment variable:

export OPENAI_API_KEY=your_openai_api_key_here  # On Unix/MacOS
# OR
set OPENAI_API_KEY=your_openai_api_key_here     # On Windows

2. Navigate to the project directory and run the agent:

cd agents
python db_agent_prototype.py

3. The agent will display a welcome banner and prompt you for your first query.

4. Example queries:

   • "Please retrieve details for txnd-3:2007-cv-01697"
   • "What documents are available in this case?"
   • "When was the last filing in this case?"

Requirements

The agent requires:

• OpenAI API key (for GPT-4.1 model)
• Internet connection to access the deployed MCP server
• Python dependencies: pydantic_ai, termcolor, python-dotenv

Note: This is a prototype that uses the already deployed DocketBird MCP server at http://165.227.221.151:8040/sse.