Journely Markets README

⚠️ Not investment advice. This server returns market data for research and AI-agent use. Outputs are data, not recommendations. You are responsible for verifying any analysis and for compliance with the rules of the markets and jurisdictions you operate in.

What it is

Journely operates a public, free-tier MCP server (Model Context Protocol, spec 2025-06-18) that gives AI agents structured access to Vietnamese, Japanese, and US market data — macro indicators and forecasts, an economic calendar, sector aggregates, and per-stock fundamentals, analyst estimates and price history.

Every MCP tool is also a REST endpoint with the same data model. So you can:

• Wire it into Claude Desktop, Cursor, or any MCP-capable client → ask natural-language questions
• Call it directly from any HTTP client → drop into your own AI pipeline, notebook, or app

This repository is the public-facing landing for the server. The MCP server itself runs at https://api.journely.me/api/v1/journely/mcp — there's nothing to install or self-host.

Why it exists

In 2026, every "Top MCP servers for financial data" roundup covers the same US-first providers (EODHD, Finnhub, Financial Modeling Prep, Alpha Vantage, MarketXLS, Financial Datasets). Vietnamese market coverage is thin or paid-only; broker-tied servers exist but lock you to one execution venue. Journely is broker-neutral, multi-market, and free at the tier most indie and research workloads need.

Quick start

Option 1 — Claude Desktop (MCP)

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "journely": {
      "url": "https://api.journely.me/api/v1/journely/mcp",
      "headers": {
        "Authorization": "Bearer jrn_live_YOUR_TOKEN"
      }
    }
  }
}

Get a free token at https://journely.me/settings/api-keys. Restart Claude Desktop. All 9 tools will appear and Claude can call them automatically.

Try a prompt:

"Pull VIC's last 5 years of revenue and margins, then check where Vietnamese inflation and rates are heading."

Option 2 — cURL (REST)

export JOURNELY_TOKEN="your-token-here"

# Vietnam macro indicators
curl -H "Authorization: Bearer $JOURNELY_TOKEN" \
  "https://api.journely.me/api/v1/journely/data/macro/indicators?country=VN"

# VIC (Vingroup) snapshot + quote
curl -H "Authorization: Bearer $JOURNELY_TOKEN" \
  "https://api.journely.me/api/v1/journely/data/stocks/VIC/overview?country=VN"

# VIC income statement (annual)
curl -H "Authorization: Bearer $JOURNELY_TOKEN" \
  "https://api.journely.me/api/v1/journely/data/stocks/VIC/statements?country=VN&type=income"

Option 3 — Python (or any HTTP client)

import httpx

client = httpx.Client(
    base_url="https://api.journely.me/api/v1/journely",
    headers={"Authorization": f"Bearer {TOKEN}"},
)

# Sector snapshot (broad-market, not country-split): P/E, margin, 1Y change
r = client.get("/data/sectors", params={"level": "sector"})
print(r.json())

Tools

All 9 tools are exposed via both MCP and REST. One-to-one parity, same data model.

There is no ticker-search tool — pass any US / JP / VN symbol you already know (e.g. AAPL, 7203, FPT).

Full OpenAPI 3.1 spec with interactive ReDoc UI: https://journely.me/api-docs MCP transport details and tool schemas: https://journely.me/api-docs/mcp

Pricing

Free tier with reasonable rate limits — designed for indie developers, research, and most agent workloads.

Only tools/call counts against quota — initialize, tools/list and ping are free.

No card required to get a free key. No marketing emails after signup.

Good for

• AI agents that need Vietnamese / Japanese / US market context
• Backtesting and analytics on VN-listed equities
• LLM-driven investment research workflows (Claude, GPT, Gemini all supported via MCP or REST)
• Vietnamese-diaspora investors building personal tooling
• Anyone learning to invest who wants real data behind their AI prompts

Not for

• Order execution. No trading, positions, or orders endpoints — research data only.
• HFT. Pricing is updated frequently enough for fundamental and research workflows, not for millisecond strategies.
• Investment advice. Outputs are data, not recommendations.

How it compares

Status

Feedback and contributions

This is a docs-and-examples repository for a hosted service. The MCP server itself isn't open-source (yet). To contribute:

• Bugs or wrong data: open a GitHub issue with the exact tool call and what you expected
• Tool requests: open an issue, tag enhancement
• Built something cool with it: PR a link to the examples/ directory or DM @journely on X

Disclaimer

Nothing in this repository or the data returned by the Journely MCP server constitutes investment, legal, tax, or accounting advice. Data is provided as-is, on a best-effort basis. Markets move; data feeds occasionally lag or correct. Verify before you act.

License

MIT for this repository's contents (README, examples). The Journely service itself is governed by its Terms of Service.

Built by Trung Vu — Tokyo. Vietnamese. FIRE'd. Indie founder. Reach out: hello@journely.me · journely.me · X / Twitter