edgartools — AI Integration Reference

edgartools — AI Integration Reference

Table of Contents

• Installation
• MCP Server Setup
• MCP Tools Reference
• Built-in AI Features
• Skills for Claude
• Troubleshooting

Installation

# Core library
uv pip install edgartools

# For MCP server and Skills
uv pip install "edgartools[ai]"

MCP Server Setup

The MCP server gives any MCP-compatible client (Claude Desktop, Cursor, Cline, Continue.dev) direct access to SEC data.

Option 1: uvx (Recommended — zero install)

Add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "edgartools": {
      "command": "uvx",
      "args": ["--from", "edgartools[ai]", "edgartools-mcp"],
      "env": {
        "EDGAR_IDENTITY": "Your Name your.email@example.com"
      }
    }
  }
}

If you get "spawn uvx ENOENT" on macOS, use the full path: which uvx.

Option 2: Python (when edgartools already installed)

{
  "mcpServers": {
    "edgartools": {
      "command": "python3",
      "args": ["-m", "edgar.ai"],
      "env": {
        "EDGAR_IDENTITY": "Your Name your.email@example.com"
      }
    }
  }
}

On Windows, use python instead of python3.

Option 3: Docker

FROM python:3.12-slim
RUN pip install "edgartools[ai]"
ENV EDGAR_IDENTITY="Your Name your.email@example.com"
ENTRYPOINT ["python", "-m", "edgar.ai"]

docker build -t edgartools-mcp .
docker run -i edgartools-mcp

Verify Setup

python -m edgar.ai --test

MCP Tools Reference

edgar_company

Get company profile, financials, recent filings, and ownership in one call.

Example prompts:

• "Show me Apple's profile and latest financials"
• "Get Microsoft's recent filings and ownership data"

edgar_search

Search for companies or filings.

edgar_filing

Read filing content or specific sections.

Example prompts:

• "Show me the risk factors from Apple's latest 10-K"
• "Get the MD&A section from Tesla's most recent annual report"

edgar_compare

Compare companies side-by-side or by industry.

edgar_ownership

Insider transactions, institutional holders, or fund portfolios.

Built-in AI Features

These work without the [ai] extra.

.docs Property

Every major object has searchable API docs:

from edgar import Company

company = Company("AAPL")
company.docs                       # Full API reference
company.docs.search("financials")  # Search specific topic

# Also available on:
filing.docs
filings.docs
xbrl.docs
statement.docs

.to_context() Method

Token-efficient output for LLM context windows:

company = Company("AAPL")

# Control detail level
company.to_context(detail='minimal')    # ~100 tokens
company.to_context(detail='standard')   # ~300 tokens (default)
company.to_context(detail='full')       # ~500 tokens

# Hard token limit
company.to_context(max_tokens=200)

# Also available on:
filing.to_context(detail='standard')
filings.to_context(detail='minimal')
xbrl.to_context(detail='standard')
statement.to_context(detail='full')

Skills for Claude

Skills teach Claude to write better edgartools code by providing patterns and best practices.

Install for Claude Code (auto-discovered)

from edgar.ai import install_skill
install_skill()  # installs to ~/.claude/skills/edgartools/

Install for Claude Desktop (upload as project knowledge)

from edgar.ai import package_skill
package_skill()  # creates edgartools.zip
# Upload the ZIP to a Claude Desktop Project

Skill Domains

When to Use Which

Filing to Markdown for LLM Processing

company = Company("NVDA")
filing = company.get_filings(form="10-K").latest()

# Export to markdown for LLM analysis
md = filing.markdown(include_page_breaks=True)

with open("nvidia_10k_for_analysis.md", "w") as f:
    f.write(md)

print(f"Saved {len(md)} characters")

Troubleshooting

"EDGAR_IDENTITY environment variable is required" Add your name and email to the env section of your MCP config. The SEC requires identification.

"Module edgar.ai not found" Install with AI extras: uv pip install "edgartools[ai]"

"python3: command not found" (Windows) Use python instead of python3 in MCP config.

MCP server not appearing in Claude Desktop

1. Check config file location for your OS
2. Validate JSON syntax
3. Restart Claude Desktop completely
4. Run python -m edgar.ai --test to verify

Skills not being picked up

1. Verify: ls ~/.claude/skills/edgartools/
2. For Claude Desktop, upload as ZIP to a Project
3. Skills affect code generation, not conversational responses