@uh-joan/sec-mcp-server
Advanced tools
MCP server for SEC EDGAR (Electronic Data Gathering, Analysis, and Retrieval) system data access. Provides search and retrieval of company filings, financial statements, and XBRL data from the U.S. Securities and Exchange Commission using the official EDG
A production-ready Model Context Protocol (MCP) server that provides comprehensive access to the U.S. Securities and Exchange Commission's EDGAR (Electronic Data Gathering, Analysis, and Retrieval) system. This server enables AI assistants and applications to search, retrieve, and analyze public company filings, financial statements, and dimensional XBRL data from the SEC's database.
Extract precise financial facts with complete dimensional context:
{
"method": "build_fact_table",
"cik_or_ticker": "JNJ",
"target_value": 638000000,
"tolerance": 50000000
}
Returns dimensional facts like:
us-gaap:NonUsMember + jnj:MedTechMember + jnj:ElectrophysiologyMemberAutomatically classifies and analyzes financial facts:
The server provides a unified sec_edgar tool with 10 powerful methods:
search_companies)Find companies by name or ticker using SEC's official database.
{
"method": "search_companies",
"query": "Johnson & Johnson"
}
get_company_cik)Convert ticker symbols to Central Index Keys with validation.
{
"method": "get_company_cik",
"ticker": "JNJ"
}
get_company_submissions)Retrieve complete filing history with enhanced metadata.
{
"method": "get_company_submissions",
"cik_or_ticker": "0000200406"
}
get_company_facts)Access all XBRL financial data with structured organization.
{
"method": "get_company_facts",
"cik_or_ticker": "JNJ"
}
get_company_concept)Extract specific financial concepts with historical trends.
{
"method": "get_company_concept",
"cik_or_ticker": "JNJ",
"taxonomy": "us-gaap",
"tag": "RevenueFromContractWithCustomerExcludingAssessedTax"
}
get_frames_data)Analyze aggregated data across companies and periods.
{
"method": "get_frames_data",
"taxonomy": "us-gaap",
"tag": "Assets",
"unit": "USD",
"frame": "CY2024Q1I"
}
get_dimensional_facts)NEW: Extract facts with complete dimensional context from XBRL instance documents.
{
"method": "get_dimensional_facts",
"cik_or_ticker": "JNJ",
"accession_number": "0000200406-25-000119",
"search_criteria": {
"concept": "RevenueFromContractWithCustomerExcludingAssessedTax",
"valueRange": {
"min": 588000000,
"max": 688000000
},
"dimensions": {
"subsegment": "Electrophysiology"
}
}
}
search_facts_by_value)NEW: Find financial facts around specific target values with filters.
{
"method": "search_facts_by_value",
"cik_or_ticker": "JNJ",
"target_value": 638000000,
"tolerance": 50000000,
"filters": {
"concept": "Revenue",
"formType": "10-Q"
}
}
build_fact_table)NEW: Generate comprehensive dimensional fact tables with business intelligence.
{
"method": "build_fact_table",
"cik_or_ticker": "JNJ",
"target_value": 638000000,
"tolerance": 50000000,
"options": {
"maxRows": 25,
"showDimensions": true,
"sortBy": "deviation"
}
}
filter_filings)Enhanced filtering with date ranges and form types.
{
"method": "filter_filings",
"filings": [...],
"form_type": "10-Q",
"start_date": "2024-01-01",
"end_date": "2024-12-31"
}
data.sec.gov APIs per SEC guidelinesSEC-Research-Tool/1.0 (contact@research.org)<ix:nonFraction>, <ix:fraction>, and context relationships{
"method": "build_fact_table",
"cik_or_ticker": "AAPL",
"target_value": 100000000000,
"tolerance": 10000000000
}
Find all facts around $100B for Apple with dimensional context
{
"method": "search_facts_by_value",
"cik_or_ticker": "TSLA",
"target_value": 20000000000,
"filters": {
"concept": "Revenue",
"dimensions": {"geography": "International"}
}
}
Analyze Tesla's international revenue performance
{
"method": "get_dimensional_facts",
"cik_or_ticker": "JPM",
"search_criteria": {
"concept": "LoanLossProvision",
"valueRange": {"min": 1000000000, "max": 5000000000}
}
}
Monitor JPMorgan's loan loss provisions with risk segmentation
{
"method": "get_frames_data",
"taxonomy": "us-gaap",
"tag": "OperatingIncomeLoss",
"unit": "USD",
"frame": "CY2024Q3I"
}
Compare operating income across all companies for Q3 2024
Add to your Claude Desktop MCP configuration:
{
"mcpServers": {
"sec-edgar": {
"command": "npx",
"args": ["@uh-joan/sec-mcp-server"]
}
}
}
Add to your Cursor MCP settings (mcp.json):
{
"servers": {
"sec-mcp-server": {
"command": "node",
"args": ["/path/to/sec-mcp-server/src/index.js"]
}
}
}
# Global installation
npm install -g @uh-joan/sec-mcp-server
# Local installation
npm install @uh-joan/sec-mcp-server
git clone https://github.com/uh-joan/sec-mcp-server.git
cd sec-mcp-server
npm install
npm run build
npm start
sec-mcp-server/
├── src/
│ ├── index.js # MCP server implementation
│ ├── edgar-api.js # SEC EDGAR API interactions
│ ├── xbrl-parser.js # iXBRL document parser
│ └── fact-table-builder.js # Business intelligence engine
├── dist/ # Built files
├── demo-fact-table.js # Demonstration script
├── package.json
└── README.md
// For academic research
headers: {
'User-Agent': 'University-Research/1.0 (research@university.edu)'
}
// For commercial analysis
headers: {
'User-Agent': 'Financial-Analysis-Tool/1.0 (contact@company.com)'
}
// Built-in rate limiting respects SEC guidelines
const rateLimitDelay = 100; // milliseconds between requests
# Test basic functionality
node demo-fact-table.js
# Test specific company
node -e "
const { buildFactTable } = require('./src/edgar-api.js');
buildFactTable('AAPL', 100000000000, 10000000000).then(console.log);
"
| Form | Description | Frequency | Key Data |
|---|---|---|---|
| 10-K | Annual Report | Yearly | Complete financials, business overview |
| 10-Q | Quarterly Report | Quarterly | Unaudited financials, interim updates |
| 8-K | Current Report | As needed | Material events, acquisitions |
| DEF 14A | Proxy Statement | Annually | Executive compensation, voting matters |
| 20-F | Foreign Annual | Yearly | Non-US company annual report |
| S-1 | Registration | As needed | IPO registration statement |
Primary financial concepts:
Assets - Total company assetsLiabilities - Total liabilitiesStockholdersEquity - Shareholders' equityRevenueFromContractWithCustomerExcludingAssessedTax - Revenue excluding taxesNetIncomeLoss - Net income or lossOperatingIncomeLoss - Operating income or lossCashAndCashEquivalents - Cash and equivalentssrt:StatementGeographicalAxis - Geographic segmentationus-gaap:StatementBusinessSegmentsAxis - Business segment breakdownus-gaap:SubsegmentsAxis - Product line subsegmentsus-gaap:StatementEquityComponentsAxis - Equity componentsus-gaap:UsMember, us-gaap:NonUsMember*:TechnologyMember, *:HealthcareMember, *:MedTechMember*:ElectrophysiologyMember, *:OrthopedicsMember{
"method": "get_dimensional_facts",
"cik_or_ticker": "JNJ",
"search_criteria": {
"concept": "RevenueFromContractWithCustomerExcludingAssessedTax",
"dimensions": {
"us-gaap:StatementBusinessSegmentsAxis": "jnj:MedTechMember",
"us-gaap:SubsegmentsAxis": "jnj:ElectrophysiologyMember"
}
}
}
{
"method": "build_fact_table",
"cik_or_ticker": "PFE",
"target_value": 15000000000,
"tolerance": 2000000000,
"options": {
"maxRows": 50,
"sortBy": "value",
"filters": {
"concept": "Revenue",
"formType": "10-Q"
}
}
}
{
"method": "search_facts_by_value",
"cik_or_ticker": "AMZN",
"target_value": 50000000000,
"tolerance": 5000000000,
"filters": {
"concept": "OperatingIncome"
}
}
Error: Request failed with status code 429
Solution: Built-in rate limiting handles this automatically
Error: Could not find CIK for ticker
Solution: Use search_companies to verify ticker symbol
Error: No recent filing found
Solution: Check filing history with get_company_submissions
Error: 403 Forbidden
Solution: Automatic fallback to Company Facts API
# Test SEC API connectivity
node -e "const {getCompanyCik} = require('./src/edgar-api.js'); getCompanyCik('AAPL').then(console.log);"
# Verify filing access
node -e "const {getCompanySubmissions} = require('./src/edgar-api.js'); getCompanySubmissions('AAPL').then(r => console.log(r.recentFilings.slice(0,3)));"
# Test dimensional parsing
node -e "const {buildFactTable} = require('./src/edgar-api.js'); buildFactTable('AAPL', 100000000000, 10000000000).then(r => console.log(r.summary));"
maxRows option for large datasets// Built-in performance tracking
console.time('fact-table-build');
const result = await buildFactTable('JNJ', 638000000, 50000000);
console.timeEnd('fact-table-build');
git clone https://github.com/uh-joan/sec-mcp-server.git
cd sec-mcp-server
npm install
npm run build
# Test new dimensional features
npm test
# Validate SEC API compliance
npm run validate-api
# Test MCP integration
npm run test-mcp
This project is licensed under the MIT License - see the LICENSE file for details.
This MCP server represents a breakthrough in financial data analysis, providing the first comprehensive dimensional XBRL fact extraction capability in the MCP ecosystem. From simple ticker lookups to complex multi-dimensional business intelligence, this server enables unprecedented analysis of SEC filing data.
From a simple User-Agent investigation to a complete dimensional analysis platform - demonstrating the power of persistent problem-solving and architectural excellence! 🚀
⚠️ Important: This is an unofficial tool. Please respect SEC's data usage guidelines and terms of service. Always verify critical financial data through official SEC sources.
FAQs
MCP server for SEC EDGAR (Electronic Data Gathering, Analysis, and Retrieval) system data access. Provides search and retrieval of company filings, financial statements, and XBRL data from the U.S. Securities and Exchange Commission using the official EDG
The npm package @uh-joan/sec-mcp-server receives a total of 20 weekly downloads. As such, @uh-joan/sec-mcp-server popularity was classified as not popular.
We found that @uh-joan/sec-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ruby maintainers from Bundler and rbenv teams are building rv to bring Python uv's speed and unified tooling approach to Ruby development.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.
Security News
AGENTS.md is a fast-growing open format giving AI coding agents a shared, predictable way to understand project setup, style, and workflows.