@macroaxis/api-mcp

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:

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:

{
  "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):

{
  "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):

[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:

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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.