Skip to content

Commit 6ff9bfb

Browse files
stefanoamorellistefanoamorelli
authored
Merge pull request #42 from stefanoamorelli/chore/update-readme
docs: simplify README
2 parents 65e0d58 + 840b639 commit 6ff9bfb

File tree

1 file changed

+53
-128
lines changed

1 file changed

+53
-128
lines changed

‎README.md‎

Lines changed: 53 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -1,180 +1,105 @@
1-
<div align="center">
2-
31
# SEC EDGAR MCP
42

5-
mcp-name: io.github.stefanoamorelli/sec-edgar-mcp
6-
7-
</div>
8-
93
<p align="center">
10-
<img alt="License: AGPL-3.0" src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" />
11-
<img alt="Python: 3.11+" src="https://img.shields.io/badge/python-3.11+-brightgreen.svg" />
12-
<img alt="Platform: Windows | Mac | Linux" src="https://img.shields.io/badge/platform-Windows%20%7C%20Mac%20%7C%20Linux-lightgrey.svg" />
13-
<img alt="Build Status" src="https://img.shields.io/badge/build-passing-brightgreen.svg" />
144
<a href="https://pypi.org/project/sec-edgar-mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/sec-edgar-mcp.svg" /></a>
155
<a href="https://anaconda.org/stefanoamorelli/sec-edgar-mcp"><img alt="Conda Version" src="https://img.shields.io/conda/vn/stefanoamorelli/sec-edgar-mcp.svg" /></a>
6+
<img alt="Python: 3.11+" src="https://img.shields.io/badge/python-3.11+-brightgreen.svg" />
7+
<img alt="License: AGPL-3.0" src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" />
168
<a href="https://mseep.ai/app/0132880c-5e83-410b-a1d5-d3df08ed7b5c"><img alt="Verified on MseeP" src="https://mseep.ai/badge.svg" /></a>
179
<a href="https://doi.org/10.5281/zenodo.17123166"><img alt="DOI" src="https://zenodo.org/badge/DOI/10.5281/zenodo.17123166.svg" /></a>
1810
</p>
1911

20-
https://github.com/user-attachments/assets/d310eb42-b3ca-467d-92f7-7d132e6274fe
21-
22-
> [!IMPORTANT]
23-
> EDGAR® and SEC® are trademarks of the U.S. Securities and Exchange Commission. This open-source project is not affiliated with or approved by the U.S. Securities and Exchange Commission.
12+
MCP server for accessing SEC EDGAR filings. Connects AI assistants to company filings, financial statements, and insider trading data with exact numeric precision.
2413

25-
## Introduction 📣
14+
Built on [edgartools](https://github.com/dgunning/edgartools).
2615

27-
SEC EDGAR MCP is an open-source MCP server that connects AI models to the rich dataset of [SEC EDGAR filings](https://www.sec.gov/edgar). EDGAR (Electronic Data Gathering, Analysis, and Retrieval) is the U.S. SEC's primary system for companies to submit official filings. It contains millions of filings and "increases the efficiency, transparency, and fairness of the securities markets" by providing free public access to corporate financial information. This project makes that trove of public company data accessible to AI assistants (LLMs) for financial research, investment insights, and corporate transparency use cases.
28-
29-
Using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) – an open standard that "enables seamless integration between LLM applications and external data sources and tools" – the SEC EDGAR MCP server exposes a comprehensive set of tools for accessing SEC filing data. Under the hood, it leverages the [EdgarTools Python library](https://github.com/dgunning/edgartools) to fetch data from official SEC sources and performs direct XBRL parsing for exact financial precision. This means an AI agent can ask questions like "What's the latest 10-K filing for Apple?" or "Show me Tesla's exact revenue from their latest 10-K" and the MCP server will retrieve the answer directly from EDGAR's official data with complete accuracy and filing references.
30-
31-
> [!TIP]
32-
> If you use this software, please cite it using the DOI below or following [CITATION.cff](CITATION.cff):
33-
>
34-
> [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17123166.svg)](https://doi.org/10.5281/zenodo.17123166)
35-
>
36-
> **APA Citation:**
37-
>
38-
> Amorelli, S. (2025). *SEC EDGAR MCP (Model Context Protocol) Server* (Version 1.0.6) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.17123166
39-
>
40-
> **BibTeX:**
41-
> ```bibtex
42-
> @software{amorelli_sec_edgar_mcp_2025,
43-
> title = {{SEC EDGAR MCP (Model Context Protocol) Server}},
44-
> author = {Amorelli, Stefano},
45-
> version = {1.0.6},
46-
> year = {2025},
47-
> month = {9},
48-
> url = {https://doi.org/10.5281/zenodo.17123166},
49-
> doi = {10.5281/zenodo.17123166}
50-
> }
51-
> ```
16+
https://github.com/user-attachments/assets/d310eb42-b3ca-467d-92f7-7d132e6274fe
5217

53-
## Usage 🚀
18+
<details>
19+
<summary>See demo video</summary>
5420

55-
Once the SEC EDGAR MCP server is running, you can connect to it with any MCP-compatible client (such as an AI assistant or the MCP CLI tool). The client will discover the available EDGAR tools and can invoke them to get real-time data from SEC filings. For example, an AI assistant could use this server to fetch a company's recent filings or query specific financial metrics without manual web searching.
21+
<a href="https://www.loom.com/share/17fcd7d891fe496f9a6b8fb85ede66bb">
22+
<img style="max-width:300px;" src="https://cdn.loom.com/sessions/thumbnails/17fcd7d891fe496f9a6b8fb85ede66bb-7f8590d1d4bcc2fb-full-play.gif">
23+
</a>
5624

57-
For comprehensive guides, examples, and tool documentation, visit the [SEC EDGAR MCP Documentation](https://sec-edgar-mcp.amorelli.tech/).
25+
</details>
5826

59-
### Docker Configuration
27+
> [!NOTE]
28+
> This project is not affiliated with or endorsed by the U.S. Securities and Exchange Commission. EDGAR and SEC are trademarks of the SEC.
6029
61-
To use SEC EDGAR MCP with Docker, add the following configuration to your MCP client:
30+
## Quick Start
6231

6332
```json
6433
{
6534
"mcpServers": {
6635
"sec-edgar-mcp": {
6736
"command": "docker",
6837
"args": [
69-
"run",
70-
"-i",
71-
"--rm",
72-
"-e",
73-
"SEC_EDGAR_USER_AGENT=Your Name (name@domain.com)",
38+
"run", "-i", "--rm",
39+
"-e", "SEC_EDGAR_USER_AGENT=Your Name (your@email.com)",
7440
"stefanoamorelli/sec-edgar-mcp:latest"
75-
],
76-
"env": {}
41+
]
7742
}
7843
}
7944
}
8045
```
8146

82-
> [!NOTE]
83-
> The `-i` flag is required to keep STDIN open in interactive mode, which is essential for MCP servers to receive JSON-RPC messages from the client.
84-
85-
**Demo**: Here's a demonstration of an AI assistant using SEC EDGAR MCP to retrieve Apple's latest filings and financial facts (click to view the video):
47+
The `-i` flag is required for MCP's JSON-RPC communication.
8648

87-
<div align="center">
88-
<a href="https://www.loom.com/share/17fcd7d891fe496f9a6b8fb85ede66bb">
89-
<img style="max-width:300px;" src="https://cdn.loom.com/sessions/thumbnails/17fcd7d891fe496f9a6b8fb85ede66bb-7f8590d1d4bcc2fb-full-play.gif">
90-
</a>
91-
<a href="https://www.loom.com/share/17fcd7d891fe496f9a6b8fb85ede66bb">
92-
<p>SEC EDGAR MCP - Demo - Watch Video</p>
93-
</a>
94-
</div>
49+
For other installation methods (pip, conda, uv), see the [documentation](https://sec-edgar-mcp.amorelli.tech/setup/quickstart).
9550

96-
In the demo above, the assistant uses SEC EDGAR MCP tools to retrieve Apple's filings and financial data, showcasing how EDGAR information is fetched and presented in real-time with exact precision and filing references. 📊
51+
## Tools
9752

98-
## Documentation 📚
53+
| Category | Tools |
54+
|----------|-------|
55+
| **Company** | CIK lookup, company info, company facts |
56+
| **Filings** | 10-K, 10-Q, 8-K retrieval, section extraction |
57+
| **Financials** | Balance sheet, income statement, cash flow (XBRL-parsed) |
58+
| **Insider Trading** | Form 3/4/5 transactions |
9959

100-
For installation and setup instructions, visit the [SEC EDGAR MCP Quickstart Guide](https://sec-edgar-mcp.amorelli.tech/setup/quickstart). For complete tool documentation, usage examples, and configuration guides, visit the [SEC EDGAR MCP Documentation](https://sec-edgar-mcp.amorelli.tech/).
60+
All responses include SEC filing URLs for verification.
10161

102-
### Running Documentation Locally
62+
## HTTP Transport
10363

104-
To run the documentation locally for development or offline access:
64+
For platforms like [Dify](https://dify.ai), use streamable HTTP instead of stdio:
10565

10666
```bash
107-
# Install Mintlify CLI globally
108-
npm i -g mintlify
109-
110-
# Navigate to the docs directory
111-
cd docs
112-
113-
# Start the development server
114-
mintlify dev
67+
python -m sec_edgar_mcp.server --transport streamable-http --port 9870
11568
```
11669

117-
The documentation will be available at `http://localhost:3000`. Any changes you make to the documentation files will be reflected in real-time.
70+
No authentication is included. Use only on private networks.
11871

119-
## Architecture 🏗️
72+
## Documentation
12073

121-
The SEC EDGAR MCP server acts as a middleman between an AI (MCP client) and the SEC's EDGAR backend:
74+
Full docs: [sec-edgar-mcp.amorelli.tech](https://sec-edgar-mcp.amorelli.tech/)
12275

123-
- 🔸 **MCP Client**: Could be an AI assistant (like [Claude](https://claude.ai/) or other MCP-compatible tools) or any app that speaks the MCP protocol. The client sends JSON-RPC requests to invoke tools and receives JSON results.
124-
125-
- 🔸 **MCP Server (SEC EDGAR MCP)**: This server defines comprehensive EDGAR tools and handles incoming requests. It features:
126-
- **Company Tools**: CIK lookup, company information, and company facts
127-
- **Filing Tools**: Recent filings, filing content, 8-K analysis, and section extraction
128-
- **Financial Tools**: Financial statements with direct XBRL parsing for exact precision
129-
- **Insider Trading Tools**: Form 3/4/5 analysis with detailed transaction data
130-
131-
- 🔸 **EDGAR Data Sources**: The server uses the [edgartools Python library](https://github.com/dgunning/edgartools) to access:
132-
- **SEC EDGAR REST API**: Official SEC endpoint for company data and filing metadata
133-
- **Direct XBRL Parsing**: Extracts financial data directly from SEC filings using regex patterns for exact numeric precision
134-
- **Filing Content**: Downloads and parses complete SEC filing documents (.txt format)
135-
136-
**Key Features**:
137-
- **Deterministic Responses**: All tools include strict instructions to prevent AI hallucination and ensure responses are based only on SEC filing data
138-
- **Exact Precision**: Financial data maintains exact numeric precision (no rounding) as filed with the SEC
139-
- **Filing References**: Every response includes clickable SEC URLs for independent verification
140-
- **Flexible XBRL Extraction**: Uses pattern matching to find financial concepts without hardcoded mappings
141-
142-
**How it works**: The MCP client discovers available tools (company lookup, financial statements, insider transactions, etc.). When invoked, each tool fetches data from SEC sources, applies deterministic processing rules, and returns structured JSON with filing references. This ensures AI responses are accurate, verifiable, and based solely on official SEC data.
143-
144-
## Integrations
145-
146-
By default, the MCP server is configured to use the [stdio](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#stdio) transport. Integrations with platforms such as [Dify](https://dify.ai) require switching to [streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http), or possibly [SSE](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse) depending on the required [backwards compatibility](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#backwards-compatibility)). Streamable HTTP can be enabled by passing a `--transport streamable-http` argument to `server.py`. The host and port to listen on default to host `0.0.0.0` and port `9870`. These values can be over-ridden using the `--host` and `--port` addresses.
147-
148-
NOTE: there is no authentication on the server, and the HTTP exposure has not been tested or assured for any particular threat model. You would be wise to limit such usage to private, firewalled networks, or private cloud networks. Having the server directly addressable from the whole internet would be unwise without additional security protections.
149-
150-
## References 📚
151-
152-
- **[SEC EDGAR](https://www.sec.gov/edgar)** – About EDGAR, SEC.gov (2024). EDGAR is the SEC's database for electronic company filings.
153-
154-
- **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)** – Official documentation and SDKs. ModelContextProtocol.io – An open standard for connecting LLMs to tools.
155-
156-
- **[EdgarTools](https://github.com/dgunning/edgartools)** – A modern Python library for accessing SEC EDGAR data with powerful filing analysis capabilities. [GitHub repo](https://github.com/dgunning/edgartools), [Documentation](https://dgunning.github.io/edgartools/).
157-
158-
159-
## Contributors 🤝
160-
161-
A big thank you to all the contributors who have helped make this project better!
76+
## Contributors
16277

16378
<a href="https://github.com/stefanoamorelli/sec-edgar-mcp/graphs/contributors">
16479
<img src="https://contrib.rocks/image?repo=stefanoamorelli/sec-edgar-mcp" />
16580
</a>
16681

167-
## License ⚖️
82+
## Citation
16883

169-
This open-source project is licensed under the [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE). This means:
170-
- You can use, modify, and distribute this software
171-
- If you modify and distribute it, you must release your changes under AGPL-3.0
172-
- If you run a modified version on a server, you must provide the source code to users
173-
- See the LICENSE file for full details
84+
If you use this software in research, please cite it:
85+
86+
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17123166.svg)](https://doi.org/10.5281/zenodo.17123166)
87+
88+
```bibtex
89+
@software{amorelli_sec_edgar_mcp_2025,
90+
title = {{SEC EDGAR MCP (Model Context Protocol) Server}},
91+
author = {Amorelli, Stefano},
92+
version = {1.0.6},
93+
year = {2025},
94+
month = {9},
95+
url = {https://doi.org/10.5281/zenodo.17123166},
96+
doi = {10.5281/zenodo.17123166}
97+
}
98+
```
17499

175-
For commercial licensing options or other licensing inquiries, please contact stefano@amorelli.tech.
100+
See [CITATION.cff](CITATION.cff) for additional formats.
176101

177-
---
102+
## License
178103

179-
© 2025 [Stefano Amorelli](https://amorelli.tech) – Released under the [GNU Affero General Public License v3.0](LICENSE). Enjoy! 🎉
104+
[AGPL-3.0](LICENSE). For commercial licensing: stefano@amorelli.tech
180105

0 commit comments

Comments
 (0)