mirror of
https://github.com/K-Dense-AI/claude-scientific-skills.git
synced 2026-03-27 07:09:27 +08:00
Support EdgarTools to access and analyze SEC Edgar filings, XBRL financial statements, 10-K, 10-Q, and 8-K reports
This commit is contained in:
Timothy Kassis
274
scientific-skills/edgartools/references/ai-integration.md
Normal file
274
scientific-skills/edgartools/references/ai-integration.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# edgartools — AI Integration Reference
|
||||
|
||||
## Table of Contents
|
||||
- [Installation](#installation)
|
||||
- [MCP Server Setup](#mcp-server-setup)
|
||||
- [MCP Tools Reference](#mcp-tools-reference)
|
||||
- [Built-in AI Features](#built-in-ai-features)
|
||||
- [Skills for Claude](#skills-for-claude)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# 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):
|
||||
|
||||
```json
|
||||
{
|
||||
"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)
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```dockerfile
|
||||
FROM python:3.12-slim
|
||||
RUN pip install "edgartools[ai]"
|
||||
ENV EDGAR_IDENTITY="Your Name your.email@example.com"
|
||||
ENTRYPOINT ["python", "-m", "edgar.ai"]
|
||||
```
|
||||
|
||||
```bash
|
||||
docker build -t edgartools-mcp .
|
||||
docker run -i edgartools-mcp
|
||||
```
|
||||
|
||||
### Verify Setup
|
||||
|
||||
```bash
|
||||
python -m edgar.ai --test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Tools Reference
|
||||
|
||||
### edgar_company
|
||||
Get company profile, financials, recent filings, and ownership in one call.
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `identifier` | Ticker, CIK, or company name (required) |
|
||||
| `include` | Sections: `profile`, `financials`, `filings`, `ownership` |
|
||||
| `periods` | Number of financial periods (default: 4) |
|
||||
| `annual` | Annual vs quarterly (default: true) |
|
||||
|
||||
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.
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `query` | Search keywords (required) |
|
||||
| `search_type` | `companies`, `filings`, or `all` |
|
||||
| `identifier` | Limit to specific company |
|
||||
| `form` | Filter by form type (e.g., `10-K`, `8-K`) |
|
||||
| `limit` | Max results (default: 10) |
|
||||
|
||||
### edgar_filing
|
||||
Read filing content or specific sections.
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `accession_number` | SEC accession number |
|
||||
| `identifier` + `form` | Alternative: company + form type |
|
||||
| `sections` | `summary`, `business`, `risk_factors`, `mda`, `financials`, or `all` |
|
||||
|
||||
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.
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `identifiers` | List of tickers/CIKs |
|
||||
| `industry` | Industry name (alternative to identifiers) |
|
||||
| `metrics` | Metrics to compare (e.g., `revenue`, `net_income`) |
|
||||
| `periods` | Number of periods (default: 4) |
|
||||
|
||||
### edgar_ownership
|
||||
Insider transactions, institutional holders, or fund portfolios.
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `identifier` | Ticker, CIK, or fund CIK (required) |
|
||||
| `analysis_type` | `insiders`, `institutions`, or `fund_portfolio` |
|
||||
| `days` | Lookback for insider trades (default: 90) |
|
||||
| `limit` | Max results (default: 20) |
|
||||
|
||||
---
|
||||
|
||||
## Built-in AI Features
|
||||
|
||||
These work without the `[ai]` extra.
|
||||
|
||||
### .docs Property
|
||||
|
||||
Every major object has searchable API docs:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```python
|
||||
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)
|
||||
|
||||
```python
|
||||
from edgar.ai import install_skill
|
||||
install_skill() # installs to ~/.claude/skills/edgartools/
|
||||
```
|
||||
|
||||
### Install for Claude Desktop (upload as project knowledge)
|
||||
|
||||
```python
|
||||
from edgar.ai import package_skill
|
||||
package_skill() # creates edgartools.zip
|
||||
# Upload the ZIP to a Claude Desktop Project
|
||||
```
|
||||
|
||||
### Skill Domains
|
||||
|
||||
| Domain | What It Covers |
|
||||
|--------|----------------|
|
||||
| **core** | Company lookup, filing search, API routing, quick reference |
|
||||
| **financials** | Financial statements, metrics, multi-company comparison |
|
||||
| **holdings** | 13F filings, institutional portfolios |
|
||||
| **ownership** | Insider transactions (Form 4), ownership summaries |
|
||||
| **reports** | 10-K, 10-Q, 8-K document sections |
|
||||
| **xbrl** | XBRL fact extraction, statement rendering |
|
||||
|
||||
### When to Use Which
|
||||
|
||||
| Goal | Use |
|
||||
|------|-----|
|
||||
| Ask Claude questions about companies/filings | MCP Server |
|
||||
| Have Claude write edgartools code | Skills |
|
||||
| Both | Install both — they complement each other |
|
||||
|
||||
---
|
||||
|
||||
## Filing to Markdown for LLM Processing
|
||||
|
||||
```python
|
||||
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
|
||||
Reference in New Issue
Block a user