Valuein MCP Server

💎 Valuein — Community, Docs, and Discovery Hub

This repository is the public home for Valuein's SEC EDGAR fundamentals data product. It is the place to:

• Find documentation (methodology, data catalog, compliance, SLA, Excel guide)
• Run examples and notebooks that connect to our live data
• Open support tickets, bug reports, and feature requests
• Discover our distribution channels — the Python SDK, the MCP server, the Excel template, and the REST API

The source code for the SDK, MCP server, and data pipeline lives in dedicated repositories. This repo is the front door.

---

📦 The Data Product

Survivorship-bias-free, point-in-time US fundamentals sourced from SEC EDGAR:

• 12M+ filings (10-K, 10-Q, 8-K, 20-F + amendments), 1990–present
• 108M+ facts across 10,000+ active and delisted US entities
• 11,966 XBRL tags normalized to ~150 canonical standard_concept values
• Cloud Parquet on Cloudflare R2 — stream with DuckDB, no local downloads

Why it's different

---

🚚 Distribution Channels

We deliver the same underlying data through five interfaces so it lands wherever you already work.

All channels authenticate with the same Stripe-issued API token and share the same tier model.

---

💳 Plans & Access

One token unlocks the SDK, MCP, Excel, and REST API — no per-channel billing.

---

⚡ Quickstart — Python SDK

1. Install

pip install valuein-sdk

2. Query real data without a token (Sample tier, no registration):

from valuein_sdk import ValueinClient

with ValueinClient() as client:
    print(client.me())                               # {plan, status, email, createdAt}
    print(client.manifest())                         # snapshot metadata
    print(client.tables())                           # loaded table names
    print(client.get_schema("fact"))                 # column → DuckDB type

    df = client.query("SELECT COUNT(*) FROM entity")
    print(df)

3. Unlock the full dataset — add a token, no code changes needed:

echo 'VALUEIN_API_KEY="your_token_here"' >> .env

4. Production pattern — context manager, typed errors, pre-built SQL templates:

from valuein_sdk import ValueinClient, ValueinError

with ValueinClient() as client:
    try:
        df = client.run_template(
            "fundamentals_by_ticker",
            ticker="AAPL",
            start_date="2020-01-01",
            end_date="2024-01-01",
            form_types=["10-K", "10-Q"],
            metrics=["TotalRevenue", "NetIncome", "OperatingCashFlow"],
        )
        print(df)
    except ValueinError as e:
        print(f"SDK error: {e}")

---

🗂️ Data Model Essentials

Full schema in docs/schema.json and docs/data_catalog.md.

Key joins

references.cik               → entity.cik
security.entity_id           → entity.cik
filing.entity_id             → entity.cik
fact.entity_id               → entity.cik
fact.accession_id            → filing.accession_id
index_membership.security_id → security.id

Date columns — which to use when

For cross-company backtests, always filter by filing_date <= trade_date. Using report_date introduces look-ahead bias.

Canonical standard_concept names

Query fact.standard_concept with canonical names like 'TotalRevenue', 'NetIncome', 'OperatingCashFlow', 'CAPEX', 'StockholdersEquity' — not raw XBRL tags ('Revenues', 'NetIncomeLoss', 'Assets'). The full canonical list lives in docs/data_catalog.md.

DuckDB query patterns that pay off

Start from references — zero joins for cross-company filters:

SELECT symbol, name, sector
FROM   references
WHERE  is_sp500 = TRUE AND is_active = TRUE AND sector ILIKE '%technology%'

LATERAL for the latest filing per company:

JOIN LATERAL (
    SELECT accession_id FROM filing
    WHERE  entity_id = r.cik AND form_type = '10-K'
    ORDER  BY filing_date DESC LIMIT 1
) f ON TRUE

Pivot multiple concepts in one fact scan:

SELECT
  MAX(CASE WHEN standard_concept = 'TotalRevenue'       THEN numeric_value END) AS revenue,
  MAX(CASE WHEN standard_concept = 'StockholdersEquity' THEN numeric_value END) AS equity
FROM   fact
WHERE  standard_concept IN ('TotalRevenue', 'StockholdersEquity')
GROUP  BY accession_id

Cash flow items: use COALESCE(derived_quarterly_value, numeric_value) — Q2/Q3 10-Qs report YTD, this column isolates the quarter. CAPEX sign varies by filer — always ABS(capex).

---

🐍 Examples in this Repository

All examples work against the SDK published on PyPI. The Sample tier runs without a token.

Python scripts (examples/python/)

Run any example:

# Sample tier — no token needed
python examples/python/getting_started.py

# Paid tier
VALUEIN_API_KEY=xxx python examples/python/pit_backtest.py

Jupyter notebooks (examples/notebooks/)

---

🛡️ Error Handling

The SDK exposes typed exceptions so your code can react appropriately to each failure mode:

from valuein_sdk import (
    ValueinClient,
    ValueinAuthError,      # HTTP 401/403 — invalid or expired token
    ValueinPlanError,      # HTTP 403 — endpoint requires a higher plan
    ValueinNotFoundError,  # HTTP 404 — table or endpoint does not exist
    ValueinRateLimitError, # HTTP 429 — includes .retry_after (seconds)
    ValueinAPIError,       # HTTP 5xx — includes .status_code
)

with ValueinClient() as client:
    try:
        df = client.query("SELECT * FROM fact LIMIT 1000")
    except ValueinAuthError:
        print("Check your VALUEIN_API_KEY — it may be expired or invalid.")
    except ValueinPlanError:
        print("This query requires a higher-tier plan. Upgrade at valuein.biz.")
    except ValueinRateLimitError as e:
        print(f"Rate limited. Retry allowed in {e.retry_after}s.")
    except ValueinAPIError as e:
        print(f"Gateway error (status {e.status_code}).")

---

📊 Excel Integration

Stream SEC fundamentals straight into Excel via Power Query — no Python, no scripts.

Requirements: Microsoft 365 (build 16.0.17531+) and an active API token.

Quick path:

1. Get the template — follow the download link in docs/excel-guide.md
2. Open in Excel — enable editing and content
3. Paste your token into the START HERE sheet
4. Click Data > Refresh All

The workbook ships with 8 pre-configured sheets: Income Statement, Balance Sheet, Cash Flow, Entities, Securities, Filings, Index Membership, and the Data Dictionary. The full walkthrough — including token setup, Named Ranges, refresh troubleshooting, and the Power Query M-language internals — is in docs/excel-guide.md.

On Excel 2019 or earlier, Parquet.Document() is unavailable; email support@valuein.biz for CSV exports.

---

🤖 MCP Discovery — AI Agents

Valuein's MCP server exposes SEC EDGAR fundamentals to any MCP-capable AI agent (Claude, Cursor, Codex, and the wider agent ecosystem).

• Endpoint: https://mcp.valuein.biz/mcp (Streamable HTTP, MCP spec 2025-11-25)
• Auth: Authorization: Bearer <your_api_token> — the same token used by the SDK and Excel
• Manifest: server.json in this repo is the source of truth for the registry listing
• Registry: registry.modelcontextprotocol.io — search for io.github.valuein/mcp-sec-edgar

Tools exposed

Configure in an AI client

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "valuein": {
      "url": "https://mcp.valuein.biz/mcp",
      "headers": { "Authorization": "Bearer YOUR_VALUEIN_API_KEY" }
    }
  }
}

Any MCP-compliant client that supports Streamable HTTP remotes will work with the same URL + Bearer token.

---

📚 Documentation

Everything in docs/ is kept in sync with the production data.

---

💬 Support & Community

GitHub Issues is the primary support channel. Four templates cover the common cases:

For private or contractual matters (DPAs, procurement, DDQs, enterprise SLAs): support@valuein.biz.

Contributions — examples, notebook improvements, documentation fixes — are welcome. See CONTRIBUTING.md for the workflow and style guide.

---

📄 License & Disclosure

Apache 2.0. See NOTICE for attribution.

This repository is provided for research and educational purposes. It is not investment advice. No warranty of fitness for any particular trading, investment, or regulatory purpose is implied.