mcp-byul

@byul/mcp

Compliant with the latest Model Context Protocol (MCP) specification.

Links

• API Documentation
• API Pricing
• Developer Documentation
• API Status

Overview

@byul/mcp is a stdio-based MCP server that proxies the Byul REST API. It exposes a small set of MCP tools and a resource that forward requests to Byul endpoints and return the original JSON response, plus a short article-count summary string.

Requirements

• Node.js 18+
• BYUL_API_KEY environment variable

Quick start

BYUL_API_KEY=byul_xxxxxxxxxxxxx npx -y @byul/mcp

Configuration

Register this server as an MCP provider in your LLM client. The client will launch the server via stdio and communicate using JSON-RPC over stdin/stdout.

Parameters

• Tools (summary; see @docs for the full spec)
  • news_fetch → proxies GET /news with filters: limit, cursor, sinceId, minImportance, q, symbol, startDate, endDate
• Resource (summary; see @docs for the full spec)
  • byul://news{?limit,cursor,sinceId,minImportance,q,symbol,startDate,endDate}

Each response contains:

• A summary string like “Returned N articles”
• The original JSON payload from the Byul API

Available Tools

news_fetch

• Description: Fetch latest financial news
• Parameters:
  • limit (number, optional) – number of articles (1-100)
  • cursor (string, optional) – pagination cursor from previous page
  • sinceId (string, optional) – return articles created after this ID
  • minImportance (number, optional) – minimum importance (1-10)
  • q (string, optional) – search query
  • symbol (string, optional) – stock symbol (e.g., AAPL)
  • startDate (string, optional) – ISO 8601 start timestamp (UTC)
  • endDate (string, optional) – ISO 8601 end timestamp (UTC)
• Example request:

Fetch top 5 news articles about AAPL from the past week

Security

• Provide the API key via the BYUL_API_KEY environment variable only. Do not hardcode credentials in code or configs.

Platform setup

1) Cursor (latest)

~/.cursor/mcp.json or project .cursor/mcp.json:

{
  "mcpServers": {
    "byul": {
      "command": "npx",
      "args": ["-y", "@byul/mcp"],
      "env": { "BYUL_API_KEY": "byul_xxxxxxxxxxxxx" }
    }
  }
}

2) Claude Code (VS Code extension)

CLI

claude mcp add -e BYUL_API_KEY=byul_xxxxxxxxxxxxx --scope user byul npx -- -y @byul/mcp

Settings JSON

{
  "mcpServers": {
    "byul": {
      "command": "npx",
      "args": ["-y", "@byul/mcp"],
      "env": { "BYUL_API_KEY": "byul_xxxxxxxxxxxxx" }
    }
  }
}

3) Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "byul": {
      "command": "npx",
      "args": ["-y", "@byul/mcp"],
      "env": { "BYUL_API_KEY": "byul_xxxxxxxxxxxxx" }
    }
  }
}

4) VS Code

Workspace .vscode/mcp.json:

{
  "mcpServers": {
    "byul": {
      "command": "npx",
      "args": ["-y", "@byul/mcp"],
      "env": { "BYUL_API_KEY": "byul_xxxxxxxxxxxxx" }
    }
  }
}

5) Windsurf

windsurf_mcp.json:

{
  "mcpServers": {
    "mcp-server-byul": {
      "command": "npx",
      "args": ["-y", "@byul/mcp"],
      "env": {
        "BYUL_API_KEY": "byul_xxxxxxxxxxxxx"
      }
    }
  }
}

6) Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "byul": {
      "command": "npx",
      "args": ["-y", "@byul/mcp"],
      "env": { "BYUL_API_KEY": "byul_xxxxxxxxxxxxx" }
    }
  }
}

If the mcpServers object does not exist, create it. This package supports stdio (local) transport only.

Troubleshooting

• Missing API key

  • Error example: Missing BYUL_API_KEY environment variable
  • Fix: set BYUL_API_KEY in your environment before launching the server

• Corporate proxy / firewall

  • npx must reach the registry to download @byul/mcp on first run; configure your proxy settings accordingly

• Windows / WSL path and env

  • PowerShell example:

    $env:BYUL_API_KEY = "byul_xxxxxxxxxxxxx"
    npx -y @byul/mcp
    

• Transport scope

  • This package covers only stdio transport. HTTP/SSE transports are intentionally not covered in this guide.

Compliant with the latest Model Context Protocol (MCP) specification.