@macroaxis/api-mcp

Macroaxis Financial Data MCP Server

This MCP server exposes Macroaxis API-backed financial data tools, including symbol discovery, lightweight symbol profiles, structured symbol statistics, analyst ratings, portfolio correlation, and portfolio optimization.

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_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_portfolio_correlation      -> /api/v1/analytics/correlation-matrix?symbols={symbols}
get_portfolio_optimization     -> /api/v1/analytics/optimize?symbols={symbols}

Call /api/v1/schema (public, no key) for the authoritative, always-current tool list and each tool's input contract.

Quick start

You don't clone or build anything. With Node.js 18+ installed, add the server to your MCP client and it runs the published package on demand via npx. Get your API key from your Macroaxis profile (a 7-day free trial on any paid plan includes API access).

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).

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.

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

Public /api/v1/status and /api/v1/schema allow 10 requests per 60 seconds without a key. Authenticated data endpoints allow 60 requests per 60 seconds. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Window-Seconds, X-RateLimit-Reset, and Retry-After on 429.