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

Claude Desktop Example

{
  "mcpServers": {
    "macroaxis-api": {
      "command": "node",
      "args": [
        "/absolute/path/to/macroaxis2/mcp/macroaxis-api/src/server.js"
      ],
      "env": {
        "MACROAXIS_API_BASE_URL": "https://www.macroaxis.com",
        "MACROAXIS_API_KEY": "YOUR_MACROAXIS_API_KEY"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "macroaxis-api-local": {
      "command": "node",
      "args": [
        "/absolute/path/to/macroaxis2/mcp/macroaxis-api/src/server.js"
      ],
      "env": {
        "MACROAXIS_API_BASE_URL": "http://localhost:8080",
        "MACROAXIS_API_KEY": "YOUR_MACROAXIS_API_KEY"
      }
    }
  }
}

Cursor Example

{
  "mcpServers": {
    "macroaxis-api": {
      "command": "node",
      "args": [
        "/absolute/path/to/macroaxis2/mcp/macroaxis-api/src/server.js"
      ],
      "env": {
        "MACROAXIS_API_BASE_URL": "https://www.macroaxis.com",
        "MACROAXIS_API_KEY": "YOUR_MACROAXIS_API_KEY"
      }
    }
  }
}

Codex Example

[mcp_servers.macroaxis-api]
command = "node"
args = ["/absolute/path/to/macroaxis2/mcp/macroaxis-api/src/server.js"]

[mcp_servers.macroaxis-api.env]
MACROAXIS_API_BASE_URL = "https://www.macroaxis.com"
MACROAXIS_API_KEY = "YOUR_MACROAXIS_API_KEY"

API Documentation

Macroaxis API docs:

/api-docs
/api-docs/symbol-search
/api-docs/symbol-profile
/api-docs/symbol-statistics
/api-docs/symbol-analyst-ratings
/api-docs/portfolio-correlation
/api-docs/portfolio-optimization
/api-docs/mcp-server

Schema endpoint:

/api/v1/schema

Notes

• Node 18 or newer is required because the server uses native fetch.
• Use search_symbols before get_symbol_profile when a user provides a company name, fund name, crypto asset, index name, or partial ticker.
• Use get_symbol_profile before get_symbol_statistics when an AI workflow should confirm identity, listing, currency, and Macroaxis URL before pulling deeper metrics.
• API errors are surfaced to the MCP client with the Macroaxis status code and message.

Production Checklist

Before publishing broadly:

• Confirm /api/v1/status returns status: ok.
• Confirm /api/v1/search/symbols?q=apple returns ranked symbol results.
• Confirm /api/v1/symbols/AAPL/profile returns identity, listing, quote, and metadata fields.
• Confirm /api/v1/symbols/AAPL/analyst-ratings returns consensus, distribution, and price target fields.
• Confirm /api/v1/analytics/correlation-matrix?symbols=AAPL,MSFT,GOOGL returns a pairwise correlation matrix.
• Confirm /api/v1/analytics/optimize?symbols=AAPL,MSFT,GOOGL returns optimized weights and portfolio metrics.
• Confirm /api/v1/schema matches the published docs.
• Test search_symbols for company names, tickers, ETFs, funds, crypto, indexes, and empty queries.
• Test get_symbol_profile for stock, ETF, fund, crypto, and invalid symbols.
• Test get_symbol_statistics for stock, ETF, fund, crypto, and invalid symbols.
• Pin package dependency versions if publishing to npm or an internal registry.
• Run the MCP server with an absolute Node path in desktop client configs.
• Set MACROAXIS_API_BASE_URL to the production Macroaxis origin.
• Set MACROAXIS_API_KEY from the paid user's Macroaxis profile.
• Keep MACROAXIS_API_TIMEOUT_MS low enough for desktop clients; 5-15 seconds is usually reasonable.
• Confirm API-key access control and rate limiting are enabled on the Macroaxis API.
• Monitor API latency, HTTP status mix, missing fundamental-data warnings, and top requested symbols.

API Rate Limits

The Macroaxis app-level filter currently defaults to:

Public schema and status requests are limited to 10 requests per 60 seconds. API data endpoints require a valid paid-user Macroaxis API key and are limited to 60 authenticated requests per 60 seconds.

The API emits:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Window-Seconds
• X-RateLimit-Reset
• Retry-After on 429 responses

Configure the Java filter in WEB-INF/web.xml, or override with environment/JVM properties:

API_RATE_LIMIT_ENABLED
API_RATE_LIMIT_REQUESTS_PER_WINDOW
API_RATE_LIMIT_AUTHENTICATED_REQUESTS_PER_WINDOW
API_RATE_LIMIT_WINDOW_SECONDS
API_RATE_LIMIT_CLIENT_HEADER