Global MCP Stock Server

Model Context Protocol (MCP) Server for Global Stock Market Data and Analysis

overview

This project provides an MCP server for accessing stock market data, allowing your AI assistant to access real-time stock prices, chart data, company information, and more.

What is MCP (Model Context Protocol)?

The Model Context Protocol (MCP) is a standardized way for applications to provide context to Large Scale Language Models (LLMs). For more information, see the Model Context Protocol website .

function

Get real-time stock quotes
Stock history data and charts
Support for major stock indices
Company Information and Financial Data
Implemented in TypeScript and strict type checking

User Guide

Prerequisites

Node.js 18 and above
npm or yarn

How to install

Clone the repository:
git clone https://github.com/sakura-ku/grobal_mcp_stock_server.git cd grobal_mcp_stock_server
Install dependencies:
npm install
Build and run the server:
npm run build npm start

How to use

1. Setting environment variables

First, set the necessary environment variables by creating a .env file or copying and using an existing .env.example file:

# Windows PowerShellの場合
Copy-Item .env.example .env

# UNIX系システムの場合
cp .env.example .env

Edit the .env file to set the required API keys:

# 基本設定
PORT=3000
HOST=localhost
NODE_ENV=development

# Polygon.io APIキー (株価データ取得用)
POLYGON_API_KEY=your_polygon_api_key_here

# その他のAPIキー...

2. Running the Server

To start the server in development mode:

npm run dev

To start the server in production mode:

npm run build
npm run start:prod

3. How to use the API

Direct access from your browser

Once the server is running, you can access the stock data in your browser with the following URL:

http://localhost:3000/api/stock/price?symbol=AAPL

Example using cURL

You can retrieve the data from the command line using cURL:

# 株価データの取得
curl "http://localhost:3000/api/stock/price?symbol=AAPL"

# 株価履歴データの取得（過去30日間）
curl "http://localhost:3000/api/stock/history?symbol=AAPL&days=30"

Example of use from a program

Example of usage from a Node.js application:

// 株価データを取得する関数
async function getStockPrice(symbol) {
  const response = await fetch(`http://localhost:3000/api/stock/price?symbol=${symbol}`);
  const data = await response.json();
  return data;
}

// 使用例
getStockPrice('AAPL').then(data => {
  console.log(`現在の${data.symbol}の株価: ${data.price} ${data.currency}`);
});

4. Integration with AI Assistants

Please see the "Working with MCP Clients" section for information on how to integrate with AI assistants such as Claude, GPT-4, etc.

Claude usage example

Example of Claude's prompt:

株価を調べてください。
テスラ（TSLA）の現在の株価と、過去1週間の動向を教えてください。

Example of AI assistant response

テスラ（TSLA）の株価情報は以下の通りです：

現在の株価: $248.42 USD
前日比: +$5.21 (+2.14%)
取引量: 3,421,532株

過去1週間の動向:
- 7日前: $230.15
- 6日前: $232.05
- 5日前: $235.87
- 4日前: $239.14
- 3日前: $242.33
- 2日前: $243.21
- 1日前: $248.42

過去1週間で約8%の上昇トレンドを示しています。特に直近3日間で価格の上昇が加速しています。

Available Tools

Get stock price information (get_stock_price)

Gets the current stock price and related information for the specified stock.

Parameters:

symbol (string): Stock ticker symbol (e.g. AAPL, MSFT, GOOGL)

Returns:

Stock information (price, fluctuation, currency, etc.)

Integration with MCP clients

To use this MCP server in a client (Claude, Claude Desktop, or other MCP-supported application), create an mcp.json file and define the MCP server.

Example of mcp.json definition

Below is an example mcp.json definition for this server. Adding this configuration to your MCP client will allow you to access stock quotes:

{
  "servers": [
    {
      "id": "global-stock-server",
      "url": "http://localhost:3000",
      "description": "株式市場データと分析のためのMCPサーバー",
      "tools": [
        {
          "name": "get_stock_price",
          "description": "指定された株式銘柄の現在の株価と関連情報を取得します",
          "parameters": {
            "type": "object",
            "required": ["symbol"],
            "properties": {
              "symbol": {
                "type": "string",
                "description": "株式銘柄コード（例: AAPL, MSFT, GOOGL）"
              }
            }
          }
        }
      ]
    }
  ]
}

How to set up on MCP client

Save the above mcp.json definition somewhere
Open the settings screen of your MCP client (such as Claude Desktop)
Select the "Add Server" or "Import" option in the MCP Settings section
Select the mcp.json file you saved or copy and paste the contents
Save the settings and restart the client

The stock quote tool will now be available in your MCP client prompts and chats.

How to set up in Cursor IDE

In Cursor IDE, you can make the AI assistant available to your tools by adding MCP server settings to the settings.json file.

Setup Procedure

Open the Cursor settings:
- Windows/Linux: Ctrl+,
- macOS: Cmd+,
Select "Cursor Settings" and edit the settings.json file.
Add the following to the mcpServers section:

If you run it as a local project (recommended):

This project is meant to be developed and run locally, the most reliable way to do this is via the npm script:

{
  "mcpServers": {
    "global-stock-server": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/path/to/grobal_mcp_stock_server",
      "env": {
        "PORT": "3000",
        "HOST": "localhost",
        "NODE_ENV": "production",
        "STOCK_API_KEY": "your_api_key_here"
      }
    }
  }
}

If you are running in development mode:

{
  "mcpServers": {
    "global-stock-server": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/grobal_mcp_stock_server",
      "env": {
        "PORT": "3000",
        "HOST": "localhost",
        "NODE_ENV": "development",
        "STOCK_API_KEY": "your_api_key_here"
      }
    }
  }
}

Installing from GitHub Packages

This MCP server is exposed as a private npm registry using GitHub Packages, and can be installed with the following steps:

Create or edit the .npmrc file to configure authentication:

@sakura-ku:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

Set the NPM_TOKEN environment variable to your personal GitHub access token:

# Windowsの場合
$env:NPM_TOKEN="your_github_token"

# macOS/Linuxの場合
export NPM_TOKEN="your_github_token"

Install the package:

npm install @sakura-ku/grobal-mcp-stock-server

Example of settings in Cursor IDE:

{
  "mcpServers": {
    "global-stock-server": {
      "command": "npx",
      "args": ["@sakura-ku/grobal-mcp-stock-server"],
      "env": {
        "PORT": "3000",
        "HOST": "localhost",
        "STOCK_API_KEY": "your_api_key_here"
      }
    }
  }
}

For detailed configuration instructions, see How to manage a private npm registry .

troubleshooting

If the server does not start :
- Go to your project directory and run the command manually to see the error
- Verify that dependencies are installed correctly (run npm install )
- Check if the TypeScript version is correct
If you can't find the tool :
- Check if the server is running properly
- Check the tool name registered in the log output
- If necessary, run the server in debug mode with npm run dev

Developer Guide

Project Configuration

grobal_mcp_stock_server/
├── build/                # コンパイルされたJavaScriptファイル
├── src/
│   ├── __tests__/        # 統合テストとテストユーティリティ
│   ├── config/           # 設定ファイル
│   ├── data/             # データモデルとストレージ
│   ├── errors/           # カスタムエラークラス
│   ├── services/         # 外部APIとの連携サービス
│   ├── tools/            # MCPツール実装
│   │   └── __tests__/    # ツールユニットテスト
│   ├── types/            # TypeScript型定義
│   └── index.ts          # メインサーバーエントリーポイント
├── package.json          # プロジェクト設定
├── tsconfig.json         # TypeScript設定
└── README.md             # プロジェクトドキュメント

Setting up your development environment

Install development dependencies:
npm install
Start the server in development mode:
npm run dev

Development Workflow

Start the TypeScript compiler in watch mode: npm run dev
Static analysis of code: npm run lint
Automatically fix static analysis issues: npm run lint:fix
Run the test: npm test

Available scripts

Detailed explanation of the scripts defined in package.json:

Build script

build : Compiles the TypeScript code and outputs it to the dist directory.
build:dev : Build with source maps for development environment
build:prod : Build for production without source maps
clean : Delete and clean the dist directory
prebuild : Automatically run the clean script before the build

Server Startup Script

start : Starts the compiled server
start:dev : Starts the server with a development environment configuration
start:prod : Starts the server in a production configuration
dev : Development mode that watches for changes to the source code and automatically builds and restarts.

Code quality control scripts

lint : Uses ESLint to perform static analysis of TypeScript code.
lint:fix : Auto-fix code issues using ESLint

Test script

test : Runs all tests using Jest
test:watch : Run tests in watch mode, rerun on changes
test:coverage : Generates a test coverage report
test:ci : Run with test configuration for CI environment
test:unit : Runs only unit tests
test:integration : Runs only integration tests
test:services : Runs only service tests
test:debug : Runs tests in debug mode

Deployment and packaging

deploy:staging : Deploy to the staging environment
deploy:production : Deploy to the production environment
publish:package : Publishes a package to the npm registry
prepare:package : Runs a production build before packaging and creates a tarball
prepublishOnly : Run a production build before publishing the package

license

ISC

contribution

If you're interested in contributing to this project, please submit a pull request.

Integrations