Macroaxis Financial Data
Financial market, fundamental, valuation, risk, ownership, forecast, and portfolio tools.
Open source Open in the app JSON README (API)
About
Financial market, fundamental, valuation, risk, ownership, forecast, and portfolio tools.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- com.macroaxis
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.3.1
- Added
- 2026-09-07 21:05:06
- Updated
- 2026-09-07 21:05:06
- Origin id
com.macroaxis/macroaxis-api
README
# Macroaxis Financial Data MCP Server
This 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`.
## Schema-driven: tools are discovered, not hard-coded
The server holds no hard-coded tool list. On first use it fetches the public `/api/v1/schema`
document and registers every entry under `mcpTools`, using each tool's `rest` binding to turn a
tool call into the matching REST request (path/query mapping, array-to-CSV serialization, etc.).
**Adding, changing, or removing a Macroaxis API tool therefore requires no change to this server.**
Update the API schema, restart your MCP client, and the new tool appears. The same published npm
package always reflects the current API surface.
At the time of writing the schema exposes:
```text
search_symbols -> /api/v1/search/symbols?q={query}
get_symbols_batch -> /api/v1/symbols/batch?symbols={symbols}&view={view}
screen_equities -> /api/v1/screener?sectors={sectors}&marketCapMin={n}&peMax={n}&...
get_symbol_narrative -> /api/v1/symbols/{symbol}/narrative?sections={sections}
get_symbol_profile -> /api/v1/symbols/{symbol}/profile
get_symbol_statistics -> /api/v1/symbols/{symbol}/statistics
get_symbol_analyst_ratings -> /api/v1/symbols/{symbol}/analyst-ratings
get_symbol_esg -> /api/v1/symbols/{symbol}/esg
get_symbol_earnings -> /api/v1/symbols/{symbol}/earnings
get_symbol_dividends -> /api/v1/symbols/{symbol}/dividends
get_symbol_price_history -> /api/v1/symbols/{symbol}/price-history?days={days}
get_symbol_technical_indicators -> /api/v1/symbols/{symbol}/technical-indicators
get_symbol_risk -> /api/v1/symbols/{symbol}/risk
get_symbol_peers -> /api/v1/symbols/{symbol}/peers
get_symbol_ownership -> /api/v1/symbols/{symbol}/ownership
get_symbol_news -> /api/v1/symbols/{symbol}/news
get_symbol_financials -> /api/v1/symbols/{symbol}/financials
get_symbol_forecast -> /api/v1/symbols/{symbol}/forecast
get_symbol_valuation -> /api/v1/symbols/{symbol}/valuation
get_symbol_advice -> /api/v1/symbols/{symbol}/advice
get_symbol_financials_history -> /api/v1/symbols/{symbol}/financials-history
get_symbol_quality -> /api/v1/symbols/{symbol}/quality
get_symbol_insider_trades -> /api/v1/symbols/{symbol}/insider-trades
get_symbol_filings -> /api/v1/symbols/{symbol}/filings
get_portfolio_correlation -> /api/v1/analytics/correlation-matrix?symbols={symbols}
get_portfolio_optimization -> /api/v1/analytics/optimize?symbols={symbols}
get_portfolio_metrics -> /api/v1/analytics/portfolio-metrics?symbols={symbols}&weights={weights}
get_portfolio_frontier -> /api/v1/analytics/efficient-frontier?symbols={symbols}
```
Call `/api/v1/schema` (public, no key) for the authoritative, always-current tool list and each
tool's input contract.
## Quick start
Get your API key from your Macroaxis profile (a 7-day free trial on any paid plan includes API
access). Clients that support remote MCP servers can connect directly to the hosted Streamable HTTP
endpoint and send the key as a secret header:
```json
{
"mcpServers": {
"macroaxis-api": {
"url": "https://www.macroaxis.com/mcp",
"headers": { "X-Macroaxis-Api-Key": "YOUR_API_KEY" }
}
}
}
```
Do not place the key in the URL. If a client does not support remote MCP, use the npm stdio package
with Node.js 18 or newer:
**Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"macroaxis-api": {
"command": "npx",
"args": ["-y", "@macroaxis/api-mcp"],
"env": { "MACROAXIS_API_KEY": "YOUR_API_KEY" }
}
}
}
```
**Cursor** (`~/.cursor/mcp.json`) — identical shape.
**Codex** (`~/.codex/config.toml`):
```toml
[mcp_servers.macroaxis-api]
command = "npx"
args = ["-y", "@macroaxis/api-mcp"]
[mcp_servers.macroaxis-api.env]
MACROAXIS_API_KEY = "YOUR_API_KEY"
```
That's it — restart the client and the Macroaxis tools appear. If you see `spawn npx ENOENT`, your
client launched without your shell PATH; replace `npx` with its absolute path (`which npx`).
## Example prompts
Once connected, ask in plain language; the assistant selects the appropriate tool:
- "Summarize Microsoft's valuation, profitability, and risk."
- "What do analysts think of TSLA — rating, price target, and implied upside?"
- "Compare MSFT and NVDA on profitability and volatility."
- "Are AAPL, MSFT, GOOGL, and AMZN too correlated to diversify a portfolio?"
- "Optimize a portfolio of AAPL, MSFT, NVDA, V, and JNJ for a moderate risk level."
Full walkthrough with a sample session and REST/Python examples: https://www.macroaxis.com/api-docs/quickstart
## Configuration
Only `MACROAXIS_API_KEY` is required. The rest are optional:
| Name | Default | Description |
| --- | --- | --- |
| `MACROAXIS_API_KEY` | empty | Your Macroaxis API key. Sent as `X-Macroaxis-Api-Key`. |
| `MACROAXIS_API_BASE_URL` | `https://www.macroaxis.com` | API origin. Leave unset unless self-hosting or developing locally. |
| `MACROAXIS_API_TIMEOUT_MS` | `10000` | Upstream API timeout in milliseconds. |
| `MACROAXIS_API_MAX_RESPONSE_BYTES` | `5000000` | Maximum accepted upstream response size. |
| `MCP_ANALYTICS_ENABLED` | `true` | Emit privacy-minimized MCP tool-call telemetry to stderr. Set to `false` to disable it for local stdio use. |
Each successful tool call returns both a text fallback for older clients and `structuredContent` for
clients that consume typed MCP results. Every tool advertises an `outputSchema`. The structured result
also includes `mcpContext` with an explicit currency code (or `null`), documented field units,
reporting-period fields, source date, retrieval time, and measured source age when available.
## Hosted Streamable HTTP service
`src/http-server.js` runs the stateless remote transport. It binds to `127.0.0.1:3100` by default and
is intended to sit behind the Macroaxis TLS endpoint and reverse proxy. Every MCP request must carry
`X-Macroaxis-Api-Key` or `Authorization: Bearer ...`. Requests with a browser `Origin` are accepted
only when the origin is explicitly allowed.
| Name | Default | Description |
| --- | --- | --- |
| `MCP_HTTP_HOST` | `127.0.0.1` | Bind address. Keep loopback when a local reverse proxy fronts the service. |
| `MCP_HTTP_PORT` | `3100` | Internal HTTP port. |
| `MCP_HTTP_PATH` | `/mcp` | Streamable HTTP endpoint path. |
| `MCP_HTTP_ALLOWED_HOSTS` | `www.macroaxis.com,localhost,127.0.0.1` | Accepted HTTP Host values. |
| `MCP_HTTP_ALLOWED_ORIGINS` | `https://www.macroaxis.com` | Comma-separated browser origins. Requests without an Origin header remain valid for native MCP clients. |
Start the service with `npm run start:http`. The `/health` route is key-free and reports only service,
version, and transport status. See `deploy/` for a systemd unit and Apache reverse-proxy example.
MCP tool calls are not sent to website analytics. The service writes one structured
`macroaxis_mcp_tool_call` record to stderr per call, containing the tool, transport, outcome,
duration, upstream status, request ID, and server version. It does not log tool arguments or API keys.
Upstream API requests also carry `X-Macroaxis-Client: mcp`, `X-Macroaxis-Mcp-Transport`, and
`X-Macroaxis-Mcp-Tool` so API/edge logs can segment MCP traffic from website traffic.
## Local development (contributors only)
To run from a checkout instead of the published package:
```bash
npm install
npm start # against production
MACROAXIS_API_BASE_URL=http://localhost:8080 npm start # against a local Macroaxis
```
Point your client's `command`/`args` at the absolute path of `src/server.js` using your Node binary
(e.g. `/opt/homebrew/bin/node`) instead of the `npx` form above.
## Tools
### `search_symbols`
Input:
```json
{
"query": "apple",
"country": "US",
"limit": 5
}
```
Output:
Returns the structured JSON response from Macroaxis symbol search, including:
- `data.query`
- `data.country`
- `data.limit`
- `data.count`
- `data.results[].symbol`
- `data.results[].displaySymbol`
- `data.results[].name`
- `data.results[].entityType`
- `data.results[].assetType`
- `data.results[].country`
- `data.results[].exchange`
- `data.results[].url`
- `metadata`
### `get_symbol_profile`
Input:
```json
{
"symbol": "AAPL"
}
```
Output:
Returns the structured JSON response from Macroaxis, including:
- `data.symbol`
- `data.displaySymbol`
- `data.name`
- `data.entityType`
- `data.assetType`
- `data.exchange`
- `data.country`
- `data.currencyCode`
- `data.sector`
- `data.industry`
- `data.url`
- `data.quote`
- `metadata`
### `get_symbol_statistics`
Input:
```json
{
"symbol": "AAPL"
}
```
Output:
Returns the structured JSON response from Macroaxis, including:
- `data.symbol`
- `data.name`
- `data.price`
- `data.statistics.valuation`
- `data.statistics.profitability`
- `data.statistics.liquidity`
- `data.statistics.solvency`
- `data.statistics.risk`
- `data.statistics.growth`
- `data.statistics.dividends`
- `data.statistics.ownership`
- `metadata`
### `get_symbol_analyst_ratings`
Input:
```json
{
"symbol": "AAPL"
}
```
Output:
Returns the structured JSON response from Macroaxis, including:
- `data.symbol`
- `data.name`
- `data.exchange`
- `data.consensus.rating`
- `data.consensus.score`
- `data.consensus.trend`
- `data.consensus.totalAnalysts`
- `data.consensus.strongBuy`
- `data.consensus.buy`
- `data.consensus.hold`
- `data.consensus.sell`
- `data.consensus.strongSell`
- `data.priceTarget.mean`
- `data.priceTarget.high`
- `data.priceTarget.low`
- `data.priceTarget.numberOfEstimates`
- `data.priceTarget.currentPrice`
- `data.priceTarget.upsideToMean`
- `metadata`
### `get_portfolio_correlation`
Input:
```json
{
"symbols": ["AAPL", "MSFT", "GOOGL"],
"days": 180
}
```
`days` is optional (30-720, defaults to 90) and sets the trailing price window.
Output:
Returns the structured JSON response from Macroaxis, including:
- `data.symbols`
- `data.count`
- `data.pairCount`
- `data.pairs[].symbolA`
- `data.pairs[].symbolB`
- `data.pairs[].coefficient`
- `data.averageCorrelation`
- `data.mostCorrelated`
- `data.leastCorrelated`
- `metadata`
Requires at least 3 symbols; up to 25 are accepted.
### `get_portfolio_optimization`
Input:
```json
{
"symbols": ["AAPL", "MSFT", "GOOGL"],
"risk": 60,
"days": 180,
"riskFreeRate": 0.01,
"confidenceInterval": 95,
"minimumReturn": 0,
"minWeight": 2,
"maxWeight": 35,
"cashUsage": 0
}
```
Only `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.
Output:
Returns the structured JSON response from Macroaxis, including:
- `data.parameters` (effective `days`, `riskLevel`, `riskFreeRate`, `confidenceInterval`, `minimumReturn`, `minWeight`, `maxWeight`, `cashUsage`)
- `data.portfolio.expectedReturn`
- `data.portfolio.risk`
- `data.portfolio.sharpeRatio`
- `data.portfolio.diversificationScore`
- `data.allocationCount`
- `data.allocations[].symbol`
- `data.allocations[].weight`
- `data.allocations[].shares`
- `data.allocations[].marketValue`
- `metadata`
Requires at least 2 symbols; up to 25 are accepted. `risk` is optional (0-100, defaults to 60).
## REST API & full documentation
The MCP tools are thin wrappers over the Macroaxis REST API; you can call the same endpoints directly.
- Schema (public, no key): `https://www.macroaxis.com/api/v1/schema`
- Status (public, no key): `https://www.macroaxis.com/api/v1/status`
- MCP server guide: `https://www.macroaxis.com/mcp-server`
- Per-endpoint reference:
- `https://www.macroaxis.com/api-docs/symbol-search`
- `https://www.macroaxis.com/api-docs/symbol-profile`
- `https://www.macroaxis.com/api-docs/symbol-statistics`
- `https://www.macroaxis.com/api-docs/symbol-analyst-ratings`
- `https://www.macroaxis.com/api-docs/portfolio-correlation`
- `https://www.macroaxis.com/api-docs/portfolio-optimization`
`/api/v1/schema` is the single source of truth — this server discovers its tools from it, so the package always matches the live API.
## Notes
- Node.js 18+ is required (the server uses native `fetch`).
- 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.
- `get_symbol_profile` is a lightweight confirmation step before the heavier `get_symbol_statistics`.
- API errors are surfaced to the MCP client with the Macroaxis status code and message.
## Rate limits
The 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`.
Costs 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.
| Cost | Endpoint | MCP tool | Public calls / min | Paid calls / min |
|---|---|---|---|---|
| 8 | `/api/v1/symbols/{symbol}/technical-indicators` | `get_symbol_technical_indicators` | 1 | 7 |
| 8 | `/api/v1/screener` | `screen_equities` | 1 | 7 |
| 5 | `/api/v1/symbols/{symbol}/peers` | `get_symbol_peers` | 2 | 12 |
| 5 | `/api/v1/symbols/batch` | `get_symbols_batch` | 2 | 12 |
| 3 | `/api/v1/symbols/{symbol}/risk` | `get_symbol_risk` | 3 | 20 |
| 3 | `/api/v1/symbols/{symbol}/forecast` | `get_symbol_forecast` | 3 | 20 |
| 3 | `/api/v1/symbols/{symbol}/valuation` | `get_symbol_valuation` | 3 | 20 |
| 3 | `/api/v1/symbols/{symbol}/advice` | `get_symbol_advice` | 3 | 20 |
| 3 | `/api/v1/symbols/{symbol}/financials-history` | `get_symbol_financials_history` | 3 | 20 |
| 3 | `/api/v1/analytics/optimize` | `get_portfolio_optimization` | 3 | 20 |
| 3 | `/api/v1/analytics/efficient-frontier` | `get_portfolio_frontier` | 3 | 20 |
| 3 | `/api/v1/analytics/portfolio-metrics` | `get_portfolio_metrics` | 3 | 20 |
| 2 | `/api/v1/analytics/correlation-matrix` | `get_portfolio_correlation` | 5 | 30 |
| 2 | `/api/v1/symbols/{symbol}/news` | `get_symbol_news` | 5 | 30 |
| 2 | `/api/v1/symbols/{symbol}/quality` | `get_symbol_quality` | 5 | 30 |
| 2 | `/api/v1/symbols/{symbol}/insider-trades` | `get_symbol_insider_trades` | 5 | 30 |
| 2 | `/api/v1/symbols/{symbol}/filings` | `get_symbol_filings` | 5 | 30 |
| 2 | `/api/v1/symbols/{symbol}/narrative` | `get_symbol_narrative` | 5 | 30 |
| 1 | all other endpoints (search, profile, statistics, analyst-ratings, esg, earnings, dividends, price-history, ownership, financials, status, schema) | — | 10 | 60 |
`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.