{
  "markdown": "# Macroaxis Financial Data MCP Server\n\nThis MCP server exposes Macroaxis API-backed financial data tools, including symbol discovery, symbol profiles and statistics, analyst ratings, ESG scores, earnings, dividends, daily price history, technical indicators, risk metrics, peers, ownership, and price forecasts, plus portfolio correlation, optimization, metrics, and efficient-frontier analytics. It supports the published npm stdio package and the hosted Streamable HTTP endpoint at `https://www.macroaxis.com/mcp`.\n\n## Schema-driven: tools are discovered, not hard-coded\n\nThe server holds no hard-coded tool list. On first use it fetches the public `/api/v1/schema`\ndocument and registers every entry under `mcpTools`, using each tool's `rest` binding to turn a\ntool call into the matching REST request (path/query mapping, array-to-CSV serialization, etc.).\n\n**Adding, changing, or removing a Macroaxis API tool therefore requires no change to this server.**\nUpdate the API schema, restart your MCP client, and the new tool appears. The same published npm\npackage always reflects the current API surface.\n\nAt the time of writing the schema exposes:\n\n```text\nsearch_symbols                  -> /api/v1/search/symbols?q={query}\nget_symbols_batch               -> /api/v1/symbols/batch?symbols={symbols}&view={view}\nscreen_equities                 -> /api/v1/screener?sectors={sectors}&marketCapMin={n}&peMax={n}&...\nget_symbol_narrative            -> /api/v1/symbols/{symbol}/narrative?sections={sections}\nget_symbol_profile              -> /api/v1/symbols/{symbol}/profile\nget_symbol_statistics           -> /api/v1/symbols/{symbol}/statistics\nget_symbol_analyst_ratings      -> /api/v1/symbols/{symbol}/analyst-ratings\nget_symbol_esg                  -> /api/v1/symbols/{symbol}/esg\nget_symbol_earnings             -> /api/v1/symbols/{symbol}/earnings\nget_symbol_dividends            -> /api/v1/symbols/{symbol}/dividends\nget_symbol_price_history        -> /api/v1/symbols/{symbol}/price-history?days={days}\nget_symbol_technical_indicators -> /api/v1/symbols/{symbol}/technical-indicators\nget_symbol_risk                 -> /api/v1/symbols/{symbol}/risk\nget_symbol_peers                -> /api/v1/symbols/{symbol}/peers\nget_symbol_ownership            -> /api/v1/symbols/{symbol}/ownership\nget_symbol_news                 -> /api/v1/symbols/{symbol}/news\nget_symbol_financials           -> /api/v1/symbols/{symbol}/financials\nget_symbol_forecast             -> /api/v1/symbols/{symbol}/forecast\nget_symbol_valuation            -> /api/v1/symbols/{symbol}/valuation\nget_symbol_advice               -> /api/v1/symbols/{symbol}/advice\nget_symbol_financials_history   -> /api/v1/symbols/{symbol}/financials-history\nget_symbol_quality              -> /api/v1/symbols/{symbol}/quality\nget_symbol_insider_trades       -> /api/v1/symbols/{symbol}/insider-trades\nget_symbol_filings              -> /api/v1/symbols/{symbol}/filings\nget_portfolio_correlation       -> /api/v1/analytics/correlation-matrix?symbols={symbols}\nget_portfolio_optimization      -> /api/v1/analytics/optimize?symbols={symbols}\nget_portfolio_metrics           -> /api/v1/analytics/portfolio-metrics?symbols={symbols}&weights={weights}\nget_portfolio_frontier          -> /api/v1/analytics/efficient-frontier?symbols={symbols}\n```\n\nCall `/api/v1/schema` (public, no key) for the authoritative, always-current tool list and each\ntool's input contract.\n\n## Quick start\n\nGet your API key from your Macroaxis profile (a 7-day free trial on any paid plan includes API\naccess). Clients that support remote MCP servers can connect directly to the hosted Streamable HTTP\nendpoint and send the key as a secret header:\n\n```json\n{\n  \"mcpServers\": {\n    \"macroaxis-api\": {\n      \"url\": \"https://www.macroaxis.com/mcp\",\n      \"headers\": { \"X-Macroaxis-Api-Key\": \"YOUR_API_KEY\" }\n    }\n  }\n}\n```\n\nDo not place the key in the URL. If a client does not support remote MCP, use the npm stdio package\nwith Node.js 18 or newer:\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"macroaxis-api\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@macroaxis/api-mcp\"],\n      \"env\": { \"MACROAXIS_API_KEY\": \"YOUR_API_KEY\" }\n    }\n  }\n}\n```\n\n**Cursor** (`~/.cursor/mcp.json`) — identical shape.\n\n**Codex** (`~/.codex/config.toml`):\n\n```toml\n[mcp_servers.macroaxis-api]\ncommand = \"npx\"\nargs = [\"-y\", \"@macroaxis/api-mcp\"]\n\n[mcp_servers.macroaxis-api.env]\nMACROAXIS_API_KEY = \"YOUR_API_KEY\"\n```\n\nThat's it — restart the client and the Macroaxis tools appear. If you see `spawn npx ENOENT`, your\nclient launched without your shell PATH; replace `npx` with its absolute path (`which npx`).\n\n## Example prompts\n\nOnce connected, ask in plain language; the assistant selects the appropriate tool:\n\n- \"Summarize Microsoft's valuation, profitability, and risk.\"\n- \"What do analysts think of TSLA — rating, price target, and implied upside?\"\n- \"Compare MSFT and NVDA on profitability and volatility.\"\n- \"Are AAPL, MSFT, GOOGL, and AMZN too correlated to diversify a portfolio?\"\n- \"Optimize a portfolio of AAPL, MSFT, NVDA, V, and JNJ for a moderate risk level.\"\n\nFull walkthrough with a sample session and REST/Python examples: https://www.macroaxis.com/api-docs/quickstart\n\n## Configuration\n\nOnly `MACROAXIS_API_KEY` is required. The rest are optional:\n\n| Name | Default | Description |\n| --- | --- | --- |\n| `MACROAXIS_API_KEY` | empty | Your Macroaxis API key. Sent as `X-Macroaxis-Api-Key`. |\n| `MACROAXIS_API_BASE_URL` | `https://www.macroaxis.com` | API origin. Leave unset unless self-hosting or developing locally. |\n| `MACROAXIS_API_TIMEOUT_MS` | `10000` | Upstream API timeout in milliseconds. |\n| `MACROAXIS_API_MAX_RESPONSE_BYTES` | `5000000` | Maximum accepted upstream response size. |\n| `MCP_ANALYTICS_ENABLED` | `true` | Emit privacy-minimized MCP tool-call telemetry to stderr. Set to `false` to disable it for local stdio use. |\n\nEach successful tool call returns both a text fallback for older clients and `structuredContent` for\nclients that consume typed MCP results. Every tool advertises an `outputSchema`. The structured result\nalso includes `mcpContext` with an explicit currency code (or `null`), documented field units,\nreporting-period fields, source date, retrieval time, and measured source age when available.\n\n## Hosted Streamable HTTP service\n\n`src/http-server.js` runs the stateless remote transport. It binds to `127.0.0.1:3100` by default and\nis intended to sit behind the Macroaxis TLS endpoint and reverse proxy. Every MCP request must carry\n`X-Macroaxis-Api-Key` or `Authorization: Bearer ...`. Requests with a browser `Origin` are accepted\nonly when the origin is explicitly allowed.\n\n| Name | Default | Description |\n| --- | --- | --- |\n| `MCP_HTTP_HOST` | `127.0.0.1` | Bind address. Keep loopback when a local reverse proxy fronts the service. |\n| `MCP_HTTP_PORT` | `3100` | Internal HTTP port. |\n| `MCP_HTTP_PATH` | `/mcp` | Streamable HTTP endpoint path. |\n| `MCP_HTTP_ALLOWED_HOSTS` | `www.macroaxis.com,localhost,127.0.0.1` | Accepted HTTP Host values. |\n| `MCP_HTTP_ALLOWED_ORIGINS` | `https://www.macroaxis.com` | Comma-separated browser origins. Requests without an Origin header remain valid for native MCP clients. |\n\nStart the service with `npm run start:http`. The `/health` route is key-free and reports only service,\nversion, and transport status. See `deploy/` for a systemd unit and Apache reverse-proxy example.\n\nMCP tool calls are not sent to website analytics. The service writes one structured\n`macroaxis_mcp_tool_call` record to stderr per call, containing the tool, transport, outcome,\nduration, upstream status, request ID, and server version. It does not log tool arguments or API keys.\nUpstream API requests also carry `X-Macroaxis-Client: mcp`, `X-Macroaxis-Mcp-Transport`, and\n`X-Macroaxis-Mcp-Tool` so API/edge logs can segment MCP traffic from website traffic.\n\n## Local development (contributors only)\n\nTo run from a checkout instead of the published package:\n\n```bash\nnpm install\nnpm start                                      # against production\nMACROAXIS_API_BASE_URL=http://localhost:8080 npm start   # against a local Macroaxis\n```\n\nPoint your client's `command`/`args` at the absolute path of `src/server.js` using your Node binary\n(e.g. `/opt/homebrew/bin/node`) instead of the `npx` form above.\n\n## Tools\n\n### `search_symbols`\n\nInput:\n\n```json\n{\n  \"query\": \"apple\",\n  \"country\": \"US\",\n  \"limit\": 5\n}\n```\n\nOutput:\n\nReturns the structured JSON response from Macroaxis symbol search, including:\n\n- `data.query`\n- `data.country`\n- `data.limit`\n- `data.count`\n- `data.results[].symbol`\n- `data.results[].displaySymbol`\n- `data.results[].name`\n- `data.results[].entityType`\n- `data.results[].assetType`\n- `data.results[].country`\n- `data.results[].exchange`\n- `data.results[].url`\n- `metadata`\n\n### `get_symbol_profile`\n\nInput:\n\n```json\n{\n  \"symbol\": \"AAPL\"\n}\n```\n\nOutput:\n\nReturns the structured JSON response from Macroaxis, including:\n\n- `data.symbol`\n- `data.displaySymbol`\n- `data.name`\n- `data.entityType`\n- `data.assetType`\n- `data.exchange`\n- `data.country`\n- `data.currencyCode`\n- `data.sector`\n- `data.industry`\n- `data.url`\n- `data.quote`\n- `metadata`\n\n### `get_symbol_statistics`\n\nInput:\n\n```json\n{\n  \"symbol\": \"AAPL\"\n}\n```\n\nOutput:\n\nReturns the structured JSON response from Macroaxis, including:\n\n- `data.symbol`\n- `data.name`\n- `data.price`\n- `data.statistics.valuation`\n- `data.statistics.profitability`\n- `data.statistics.liquidity`\n- `data.statistics.solvency`\n- `data.statistics.risk`\n- `data.statistics.growth`\n- `data.statistics.dividends`\n- `data.statistics.ownership`\n- `metadata`\n\n### `get_symbol_analyst_ratings`\n\nInput:\n\n```json\n{\n  \"symbol\": \"AAPL\"\n}\n```\n\nOutput:\n\nReturns the structured JSON response from Macroaxis, including:\n\n- `data.symbol`\n- `data.name`\n- `data.exchange`\n- `data.consensus.rating`\n- `data.consensus.score`\n- `data.consensus.trend`\n- `data.consensus.totalAnalysts`\n- `data.consensus.strongBuy`\n- `data.consensus.buy`\n- `data.consensus.hold`\n- `data.consensus.sell`\n- `data.consensus.strongSell`\n- `data.priceTarget.mean`\n- `data.priceTarget.high`\n- `data.priceTarget.low`\n- `data.priceTarget.numberOfEstimates`\n- `data.priceTarget.currentPrice`\n- `data.priceTarget.upsideToMean`\n- `metadata`\n\n### `get_portfolio_correlation`\n\nInput:\n\n```json\n{\n  \"symbols\": [\"AAPL\", \"MSFT\", \"GOOGL\"],\n  \"days\": 180\n}\n```\n\n`days` is optional (30-720, defaults to 90) and sets the trailing price window.\n\nOutput:\n\nReturns the structured JSON response from Macroaxis, including:\n\n- `data.symbols`\n- `data.count`\n- `data.pairCount`\n- `data.pairs[].symbolA`\n- `data.pairs[].symbolB`\n- `data.pairs[].coefficient`\n- `data.averageCorrelation`\n- `data.mostCorrelated`\n- `data.leastCorrelated`\n- `metadata`\n\nRequires at least 3 symbols; up to 25 are accepted.\n\n### `get_portfolio_optimization`\n\nInput:\n\n```json\n{\n  \"symbols\": [\"AAPL\", \"MSFT\", \"GOOGL\"],\n  \"risk\": 60,\n  \"days\": 180,\n  \"riskFreeRate\": 0.01,\n  \"confidenceInterval\": 95,\n  \"minimumReturn\": 0,\n  \"minWeight\": 2,\n  \"maxWeight\": 35,\n  \"cashUsage\": 0\n}\n```\n\nOnly `symbols` is required. All other inputs are optional: `risk` (0-100, default 60), `days` (30-720, default 90), `riskFreeRate` (decimal fraction 0-1 where 0.01 = 1%, default 0.01), `confidenceInterval` (percent 1-99, default 95), `minimumReturn` (decimal fraction -1 to 1 where 0.05 = 5%, default 0), `minWeight` (percent 0-100, default 2), `maxWeight` (percent 0-100, default 35), and `cashUsage` (percent 0-100, default 0). The effective values used are echoed back under `data.parameters`. Shares and market values assume a budget of 10,000; use `weight` for budget-independent allocation.\n\nOutput:\n\nReturns the structured JSON response from Macroaxis, including:\n\n- `data.parameters` (effective `days`, `riskLevel`, `riskFreeRate`, `confidenceInterval`, `minimumReturn`, `minWeight`, `maxWeight`, `cashUsage`)\n- `data.portfolio.expectedReturn`\n- `data.portfolio.risk`\n- `data.portfolio.sharpeRatio`\n- `data.portfolio.diversificationScore`\n- `data.allocationCount`\n- `data.allocations[].symbol`\n- `data.allocations[].weight`\n- `data.allocations[].shares`\n- `data.allocations[].marketValue`\n- `metadata`\n\nRequires at least 2 symbols; up to 25 are accepted. `risk` is optional (0-100, defaults to 60).\n\n## REST API & full documentation\n\nThe MCP tools are thin wrappers over the Macroaxis REST API; you can call the same endpoints directly.\n\n- Schema (public, no key): `https://www.macroaxis.com/api/v1/schema`\n- Status (public, no key): `https://www.macroaxis.com/api/v1/status`\n- MCP server guide: `https://www.macroaxis.com/mcp-server`\n- Per-endpoint reference:\n  - `https://www.macroaxis.com/api-docs/symbol-search`\n  - `https://www.macroaxis.com/api-docs/symbol-profile`\n  - `https://www.macroaxis.com/api-docs/symbol-statistics`\n  - `https://www.macroaxis.com/api-docs/symbol-analyst-ratings`\n  - `https://www.macroaxis.com/api-docs/portfolio-correlation`\n  - `https://www.macroaxis.com/api-docs/portfolio-optimization`\n\n`/api/v1/schema` is the single source of truth — this server discovers its tools from it, so the package always matches the live API.\n\n## Notes\n\n- Node.js 18+ is required (the server uses native `fetch`).\n- Use `search_symbols` first when the user gives a company name, fund, crypto, index, or partial ticker, then pass the resolved `symbol` to the other tools.\n- `get_symbol_profile` is a lightweight confirmation step before the heavier `get_symbol_statistics`.\n- API errors are surfaced to the MCP client with the Macroaxis status code and message.\n\n## Rate limits\n\nThe budget is **per 60-second window**: 10 cost units for public (unauthenticated) clients and 60 cost units for authenticated paid users. Each call subtracts its endpoint **cost** from that budget; a call is rejected with HTTP `429` when the remaining budget is smaller than the next call's cost. The window is fixed and resets fully every 60 seconds. Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Window-Seconds`, `X-RateLimit-Reset`, and `Retry-After` on `429`.\n\nCosts are not uniform — compute-heavy endpoints consume more of the budget so a single client cannot drive disproportionate load. Every endpoint also advertises its cost in the `cost` field of its `/api/v1/schema` definition.\n\n| Cost | Endpoint | MCP tool | Public calls / min | Paid calls / min |\n|---|---|---|---|---|\n| 8 | `/api/v1/symbols/{symbol}/technical-indicators` | `get_symbol_technical_indicators` | 1 | 7 |\n| 8 | `/api/v1/screener` | `screen_equities` | 1 | 7 |\n| 5 | `/api/v1/symbols/{symbol}/peers` | `get_symbol_peers` | 2 | 12 |\n| 5 | `/api/v1/symbols/batch` | `get_symbols_batch` | 2 | 12 |\n| 3 | `/api/v1/symbols/{symbol}/risk` | `get_symbol_risk` | 3 | 20 |\n| 3 | `/api/v1/symbols/{symbol}/forecast` | `get_symbol_forecast` | 3 | 20 |\n| 3 | `/api/v1/symbols/{symbol}/valuation` | `get_symbol_valuation` | 3 | 20 |\n| 3 | `/api/v1/symbols/{symbol}/advice` | `get_symbol_advice` | 3 | 20 |\n| 3 | `/api/v1/symbols/{symbol}/financials-history` | `get_symbol_financials_history` | 3 | 20 |\n| 3 | `/api/v1/analytics/optimize` | `get_portfolio_optimization` | 3 | 20 |\n| 3 | `/api/v1/analytics/efficient-frontier` | `get_portfolio_frontier` | 3 | 20 |\n| 3 | `/api/v1/analytics/portfolio-metrics` | `get_portfolio_metrics` | 3 | 20 |\n| 2 | `/api/v1/analytics/correlation-matrix` | `get_portfolio_correlation` | 5 | 30 |\n| 2 | `/api/v1/symbols/{symbol}/news` | `get_symbol_news` | 5 | 30 |\n| 2 | `/api/v1/symbols/{symbol}/quality` | `get_symbol_quality` | 5 | 30 |\n| 2 | `/api/v1/symbols/{symbol}/insider-trades` | `get_symbol_insider_trades` | 5 | 30 |\n| 2 | `/api/v1/symbols/{symbol}/filings` | `get_symbol_filings` | 5 | 30 |\n| 2 | `/api/v1/symbols/{symbol}/narrative` | `get_symbol_narrative` | 5 | 30 |\n| 1 | all other endpoints (search, profile, statistics, analyst-ratings, esg, earnings, dividends, price-history, ownership, financials, status, schema) | — | 10 | 60 |\n\n`calls / min` is the maximum if every call in the window hits that single endpoint; mixing endpoints draws the shared budget down proportionally to each call's cost.",
  "bytes": 16128,
  "sha": "be71fcdd99f2dc6b1e31795e862e42fdb4e1ee000791f1434dc4b1ce2e21780f",
  "repo_slug": "",
  "fonte": "npm",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_macroaxis_macroaxis_api_fcd1194c/readme"
}