{"id":29114227,"url":"https://github.com/octagonai/octagon-mcp-server","last_synced_at":"2026-05-26T07:04:11.148Z","repository":{"id":282128597,"uuid":"947569884","full_name":"OctagonAI/octagon-mcp-server","owner":"OctagonAI","description":"A free MCP server to analyze and extract insights from public filings, earnings transcripts, financial metrics, stock market data, private market transactions, and deep web-based research within Claude Desktop and other popular MCP clients.","archived":false,"fork":false,"pushed_at":"2025-06-17T00:19:17.000Z","size":211,"stargazers_count":35,"open_issues_count":3,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-17T00:48:37.036Z","etag":null,"topics":["ai-agents","company-profile","debt","earnings-calls","equities","financial-analysis","fundamental-analysis","funding","fundraising","funds","indices","investors","market-intelligence","mcp-server","private-market","sec-filings","sector-analysis","stock-data"],"latest_commit_sha":null,"homepage":"https://docs.octagonagents.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OctagonAI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-12T22:40:51.000Z","updated_at":"2025-06-17T00:19:20.000Z","dependencies_parsed_at":"2025-04-22T06:30:32.637Z","dependency_job_id":"e407aa15-cd4f-4cbd-8af7-ce6f598bc566","html_url":"https://github.com/OctagonAI/octagon-mcp-server","commit_stats":null,"previous_names":["octagonai/octagon-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/OctagonAI/octagon-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctagonAI%2Foctagon-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctagonAI%2Foctagon-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctagonAI%2Foctagon-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctagonAI%2Foctagon-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OctagonAI","download_url":"https://codeload.github.com/OctagonAI/octagon-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctagonAI%2Foctagon-mcp-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262581398,"owners_count":23331914,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","company-profile","debt","earnings-calls","equities","financial-analysis","fundamental-analysis","funding","fundraising","funds","indices","investors","market-intelligence","mcp-server","private-market","sec-filings","sector-analysis","stock-data"],"created_at":"2025-06-29T11:06:12.286Z","updated_at":"2026-05-26T07:04:11.141Z","avatar_url":"https://github.com/OctagonAI.png","language":"JavaScript","funding_links":[],"categories":["Finance \u0026 Fintech"],"sub_categories":["How to Submit"],"readme":"# Octagon: MCP for Market Data\n\n[![smithery badge](https://smithery.ai/badge/@OctagonAI/octagon-mcp-server)](https://smithery.ai/server/@OctagonAI/octagon-mcp-server)\n\n![Favicon](https://docs.octagonagents.com/logo.svg) The Octagon MCP server provides specialized AI-powered financial research and analysis by integrating with the Octagon Market Intelligence API, enabling users to analyze and extract insights from public filings, earnings calls, financial metrics, private market transactions, and prediction market events within Claude Desktop and other popular MCP clients.\n\n[![Demo](https://docs.octagonagents.com/financial_model_demo_fast.gif)](https://docs.octagonagents.com/financial_model_demo.mp4)\n\n## Tools\n\n✅ `octagon-agent` orchestrates broad market intelligence analysis\n\n- Public market insights (SEC filings, transcripts, financials, stock data)\n- Private market insights (companies, funding rounds, deals, debt, investors)\n\n✅ `octagon-deep-research-agent` for comprehensive deep research\n\n- Multi-source synthesis for investment research questions\n- Best for up-to-date, cross-source thematic analysis\n\n✅ Prediction market research tooling\n\n- `octagon-prediction-markets-agent` for Kalshi event research reports\n- `prediction_markets_history` for structured historical market data retrieval\n\n## Get Your Octagon API Key\n\nTo use Octagon MCP, you need to:\n\n1. Sign up for a free account at [Octagon](https://app.octagonai.co/signup/?redirectToAfterSignup=https://app.octagonai.co/api-keys)\n2. After logging in, from left menu, navigate to **API Keys**\n3. Generate a new API key\n4. Use this API key in your configuration as the `OCTAGON_API_KEY` value\n\n## Prerequisites\n\nBefore installing or running Octagon MCP, you need to have `npx` (which comes with Node.js and npm) installed on your system.\n\n### Mac (macOS)\n\n1. **Install Homebrew** (if you don't have it):\n   ```bash\n   /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n   ```\n2. **Install Node.js (includes npm and npx):**\n\n   ```bash\n   brew install node\n   ```\n\n   This will install the latest version of Node.js, npm, and npx.\n\n3. **Verify installation:**\n   ```bash\n   node -v\n   npm -v\n   npx -v\n   ```\n\n### Windows\n\n1. **Download the Node.js installer:**\n   - Go to [https://nodejs.org/](https://nodejs.org/) and download the LTS version for Windows.\n2. **Run the installer** and follow the prompts. This will install Node.js, npm, and npx.\n3. **Verify installation:**\n   Open Command Prompt and run:\n   ```cmd\n   node -v\n   npm -v\n   npx -v\n   ```\n\nIf you see version numbers for all three, you are ready to proceed with the installation steps below.\n\n## Installation\n\n### Running on Claude Desktop\n\nTo configure Octagon MCP for Claude Desktop:\n\n1. Open Claude Desktop\n2. Go to Settings \u003e Developer \u003e Edit Config\n3. Add the following to your `claude_desktop_config.json` (Replace `your-octagon-api-key` with your Octagon API key):\n\n```json\n{\n  \"mcpServers\": {\n    \"octagon-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"octagon-mcp@latest\"],\n      \"env\": {\n        \"OCTAGON_API_KEY\": \"YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\n4. Restart Claude for the changes to take effect\n\n### Running on Cursor\n\nConfiguring Cursor Desktop 🖥️\nNote: Requires Cursor version 0.45.6+\n\nTo configure Octagon MCP in Cursor:\n\n1. Open Cursor Settings\n2. Go to Features \u003e MCP Servers\n3. Click \"+ Add New MCP Server\"\n4. Enter the following:\n   - Name: \"octagon-mcp\" (or your preferred name)\n   - Type: \"command\"\n   - Command: `env OCTAGON_API_KEY=your-octagon-api-key npx -y octagon-mcp`\n\n\u003e If you are using Windows and are running into issues, try `cmd /c \"set OCTAGON_API_KEY=your-octagon-api-key \u0026\u0026 npx -y octagon-mcp\"`\n\nReplace `your-octagon-api-key` with your Octagon API key.\n\nAfter adding, refresh the MCP server list to see the new tools. The Composer Agent will automatically use Octagon MCP when appropriate, but you can explicitly request it by describing your investment research needs. Access the Composer via Command+L (Mac), select \"Agent\" next to the submit button, and enter your query.\n\n### Running with npx\n\n```bash\nenv OCTAGON_API_KEY=your_octagon_api_key npx -y octagon-mcp\n```\n\n### Manual Installation\n\n```bash\nnpm install -g octagon-mcp\n```\n\n## Documentation\n\nFor comprehensive documentation on using Octagon agents, please visit our official documentation at:\n[https://docs.octagonagents.com](https://docs.octagonagents.com)\n\nThe documentation includes:\n\n- Detailed API references\n- Agent-specific query guidelines\n- Examples and use cases\n- Best practices for investment research\n\nFor the latest hosted MCP client setup guide, see:\n\n- [Octagon MCP Server Guide](https://docs.octagonagents.com/guide/mcp-server.html)\n\n## Available Tools\n\nThe MCP server currently exposes the following tools:\n\n### `octagon-agent`\n\nOrchestrates public and private market intelligence analysis.\n\n**Parameters**\n\n- `prompt` (string, required): natural language research request.\n- `conversation` (string, optional): existing Octagon conversation ID to continue a prior `octagon-agent` thread. Omit this on the first turn.\n- `newConversation` (boolean, optional): if `true`, starts a fresh Octagon thread for the active session/thread anchor. Recommended for the first turn of a brand new visible chat in top-layer hosts such as Claude Desktop.\n\n**Threaded usage**\n\n`octagon-agent` is the only MCP tool that forwards Octagon conversation threading. It is a stateful tool and expects session continuity. The MCP resolves session/thread state in this order:\n\n1. stored conversation for MCP transport session identity, when the transport actually provides it\n2. stored conversation for the server-managed default `stdio` session\n3. explicit `conversation` can still override the active session conversation for that call\n\nThis package currently runs as a `stdio` MCP server. In `stdio` mode, the server automatically establishes a process-local session for continuity across calls. Most local hosts such as Claude Desktop or Cursor can therefore use `octagon-agent` without supplying any extra threading fields for basic follow-up behavior.\n\nWhen a top-layer host knows a call is the first turn of a new visible chat, it should pass `newConversation: true`. That explicitly clears any stored Octagon thread for the active MCP session anchor before the call, which prevents stale continuity when a `stdio` host reuses the same long-lived MCP process across multiple visible chats.\n\nThis means you can use any of these patterns:\n\n1. First call: send only `prompt`\n2. Let the MCP host preserve transport session continuity or rely on the default stdio session\n3. Second call: either\n   - send the new `prompt` in the same MCP session, or\n   - keep using the same stdio MCP process, or\n   - explicitly pass the previous `conversation`\n\nTransport session identity is the canonical continuity primitive for standards-compliant stateful MCP transports. For local `stdio` usage, the server-managed process session provides default continuity.\n\nSession identity and Octagon conversation identity are different concepts:\n\n- MCP session identity controls server-side continuity across tool calls\n- Octagon `conversation` controls the active Octagon thread inside that session\n\nThe MCP result keeps the answer in `content`, and also returns structured metadata for orchestrators in `structuredContent`:\n\n```json\n{\n  \"model\": \"octagon-agent\",\n  \"text\": \"Which stock would you like the latest price for?\",\n  \"conversation\": \"conv_123\",\n  \"responseId\": \"resp_123\",\n  \"followUp\": {\n    \"required\": true,\n    \"inputTemplate\": \"\u003cticker or company name\u003e\",\n    \"instructions\": \"Reply with just the missing detail and reuse the conversation value from this response.\"\n  }\n}\n```\n\nExplicit carry-forward example:\n\n```json\n{\n  \"prompt\": \"AAPL\",\n  \"conversation\": \"conv_123\"\n}\n```\n\nNew visible chat example:\n\n```json\n{\n  \"prompt\": \"Analyze Apple\",\n  \"newConversation\": true\n}\n```\n\nExplicit refresh example:\n\n```json\n{\n  \"prompt\": \"Start a fresh Octagon thread for this chat\",\n  \"newConversation\": true\n}\n```\n\n**Stateful tool policy**\n\n- `octagon-agent`: stateful, uses a usable continuity anchor. In `stdio` hosts, that defaults to the server-managed process session unless you provide explicit `conversation`\n- other MCP tools: stateless and may run without session continuity\n\nExample:\n\n```text\nCompare NVIDIA and AMD on latest quarterly revenue growth, margins, and management commentary.\n```\n\nMore examples:\n\n- \"What were Amazon's revenue and net income figures in Q4 2023?\"\n- \"Analyze Tesla's R\u0026D spending trends over the last 3 years.\"\n- \"What guidance did NVIDIA's CEO provide regarding AI chip demand in their latest earnings call?\"\n- \"Compare the price-to-earnings, price-to-sales, and EV/EBITDA ratios for the top 5 semiconductor companies.\"\n- \"What was Anthropic's latest funding round size, valuation, and key investors?\"\n- \"How many investments did Andreessen Horowitz make in AI startups in the last 12 months?\"\n\n### `octagon-deep-research-agent`\n\nPerforms comprehensive multi-source deep research and synthesis.\n\n**Parameters**\n\n- `prompt` (string, required): natural language research request.\n\nExample:\n\n```text\nResearch the impact of lower interest rates on late-stage private software valuations over the next 12 months.\n```\n\nMore examples:\n\n- \"Extract all data fields from zillow.com/san-francisco-ca/\"\n- \"Research the financial impact of Apple's privacy changes on digital advertising companies' revenue and margins\"\n- \"Retrieve historical Bitcoin price data from 2023 and analyze the price volatility trends\"\n- \"Analyze the competitive dynamics in the EV charging infrastructure market\"\n\n### `octagon-prediction-markets-agent`\n\nGenerates research reports for Kalshi prediction market events.\n\n**Parameters**\n\n- `prompt` (string, required): natural language research request.\n- `cache` (boolean, optional): controls agent variant routing.\n  - omitted: `prediction-markets-agent`\n  - `false`: `prediction-markets-agent:refresh`\n  - `true`: `prediction-markets-agent:cache`\n\nExample:\n\n```text\nGenerate a report for the Kalshi market https://kalshi.com/markets/kxbtcy/btc-price-range-eoy/kxbtcy-27jan0100\n```\n\n### `prediction_markets_history`\n\nFetches historical data for a prediction market event ticker with optional pagination and time filters.\n\n**Parameters**\n\n- `event_ticker` (string, required)\n- `limit` (number, optional)\n- `cursor` (string, optional)\n- `captured_from` (string, optional)\n- `captured_to` (string, optional)\n- `include_analysis` (boolean, optional; when true, requests analysis columns)\n\nExample:\n\n```text\nFetch historical data for the Kalshi event https://kalshi.com/markets/kxbtcy/btc-price-range-eoy/kxbtcy-27jan0100\n```\n\n## Troubleshooting\n\n1. **API Key Issues**: Ensure your Octagon API key is correctly set in the environment or config file.\n2. **Connection Issues**: Make sure the connectivity to the Octagon API is working properly.\n3. **Rate Limiting**: If you encounter rate limiting errors, reduce the frequency of your requests.\n\n## License\n\nMIT\n\n## Individual Specialized MCP Servers\n\nWhile this server provides comprehensive market intelligence combining all our specialized agents, you can also use our individual MCP servers for specific use cases:\n\n### Public Market Data Servers\n\n- **[Octagon SEC Filings MCP](https://github.com/OctagonAI/octagon-sec-filings-mcp)** - Dedicated server for SEC filings analysis\n- **[Octagon Earnings Transcripts MCP](https://github.com/OctagonAI/octagon-earnings-transcripts-mcp)** - Specialized for earnings call transcript analysis\n- **[Octagon Stock Market Data MCP](https://github.com/OctagonAI/octagon-stock-market-data-mcp)** - Focused on stock market data access\n- **[Octagon Financial Statements MCP](https://github.com/OctagonAI/octagon-financial-statements-mcp)** - Financial metrics and ratios analysis\n- **[Octagon 13F Holdings MCP](https://github.com/OctagonAI/octagon-13f-holdings-mcp)** - Institutional ownership and Form 13F filings\n\n### Private Market Data Servers\n\n- **[Octagon Private Companies MCP](https://github.com/OctagonAI/octagon-private-companies-mcp)** - Private company research and intelligence\n- **[Octagon Investors MCP](https://github.com/OctagonAI/octagon-investors-mcp)** - Investor profiles and investment strategies\n- **[Octagon Funding Data MCP](https://github.com/OctagonAI/octagon-funding-data-mcp)** - Startup funding rounds and venture capital data\n\n### Research Tools\n\n- **[Octagon Deep Research MCP](https://github.com/OctagonAI/octagon-deep-research-mcp)** - Comprehensive research and web scraping capabilities\n\n---\n\n⭐ Star this repo if you find it helpful!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctagonai%2Foctagon-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foctagonai%2Foctagon-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctagonai%2Foctagon-mcp-server/lists"}