wrds-mcp

An MCP server that gives AI assistants (Claude Code, Claude Desktop, etc.) natural language access to WRDS financial data for credit and equity analysis.

29 tools across bonds, credit ratings, financials, equity, loans, screening, and comps — plus a guarded SQL escape hatch and schema discovery for ad-hoc analysis.

Requires a WRDS account. This tool is a client for WRDS (Wharton Research Data Services). You must have your own WRDS subscription (academic or institutional) to use it. This project is not affiliated with, endorsed by, or sponsored by WRDS or the Wharton School.

Prerequisites

• Python 3.10+
• A WRDS account with access to the datasets you want to query (CRSP, Compustat, TRACE, FISD, DealScan, etc.)

Installation

pip install wrds-mcp

Or from GitHub:

pip install git+https://github.com/marianosalinas/wrds-mcp.git

For development:

git clone https://github.com/marianosalinas/wrds-mcp.git
cd wrds-mcp
pip install -e ".[dev]"

Configuration

1. WRDS Credentials

Create a .env file in your working directory or set environment variables:

WRDS_USERNAME=your_username
WRDS_PASSWORD=your_password

Or copy the included example:

cp .env.example .env

2. Add to Claude Code

Create a .mcp.json in your project directory:

{
  "mcpServers": {
    "wrds": {
      "command": "wrds-mcp",
      "type": "stdio"
    }
  }
}

Or add to your global Claude Code settings (~/.claude/settings.json):

{
  "mcpServers": {
    "wrds": {
      "command": "wrds-mcp"
    }
  }
}

3. Add to Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "wrds": {
      "command": "wrds-mcp"
    }
  }
}

Tools

Bonds (TRACE / FISD / bondret)

Credit Ratings (bondret + Compustat)

Financial Metrics (Compustat)

Equity (CRSP)

Syndicated Loans (DealScan)

Screening & Relative Value (bondret)

Comps (multi-source)

Discovery & Ad-hoc

Example Prompts

Once configured, just ask Claude naturally:

• "What's Ford's credit profile? Include ratings, leverage, and bond spreads."
• "Compare F, GM, and STLA — build me a comps table."
• "Screen for BB-rated issuers with leverage under 4x and market cap over $5B."
• "Show me the HY market benchmark returns for the last 12 months."
• "Is Ford's 2030 bond cheap or rich relative to BBB peers?"
• "What are the covenant terms on Delta's syndicated loans?"
• "Pull TRACE transactions for Apple bonds in Q4 2024."

Data Sources

Architecture

src/wrds_mcp/
├── server.py             # FastMCP entry point, mounts 9 sub-servers
├── db/connection.py      # Singleton WRDS connection with retry
└── tools/
    ├── catalog.py        # Tier 3: discovery (3 tools)
    ├── query.py          # Tier 2: guarded SQL (1 tool)
    ├── equity.py         # Tier 1: CRSP stocks (3 tools)
    ├── bonds.py          # Tier 1: TRACE/FISD/bondret (6 tools)
    ├── ratings.py        # Tier 1: credit ratings (2 tools)
    ├── financials.py     # Tier 1: Compustat fundamentals (6 tools)
    ├── loans.py          # Tier 1: DealScan loans (2 tools)
    ├── screening.py      # Tier 1: screening & relative value (4 tools)
    └── comps.py          # Tier 1: comps table (1 tool)

Three tiers:

1. Curated tools (25) — domain logic, auto-routing, multi-source resolution
2. Guarded SQL (1) — escape hatch for ad-hoc queries with safety validation
3. Discovery (3) — catalog, schema introspection, identifier resolution

Testing

pytest

307 tests, 90% coverage. All tests mock the WRDS connection — no credentials needed to run them.

Disclaimer

This project is an independent, open-source tool. It is not affiliated with, endorsed by, or sponsored by WRDS, the Wharton School, or the University of Pennsylvania.

• You are responsible for complying with your WRDS subscription terms and any data redistribution restrictions.
• This tool provides read-only access to data you are already licensed to use — it does not bypass any access controls.
• Nothing in this tool constitutes financial advice. Data is provided as-is for research and analysis purposes.

License

MIT