WIND Stock Index Basic Data MCP Server

This is a read-only MCP server that provides stock index basic information from the Oracle table WIND_IMP.AINDEXDESCRIPTION to local and LAN agents.

It currently provides two tools:

• get_index_by_code(code): exact lookup by S_INFO_CODE, e.g. 000300;

• search_indices_by_name(name, limit=20): search by index name fragment, returning at most 100 records.

The server does not accept SQL and provides no database write operations. Queries use fixed SQL and Oracle bind parameters.

Runtime Environment

• Windows 10/11;

• Python 3.11 or later;

• An accessible Oracle host, port, and Service Name is prepared;

• The first version uses python-oracledb Thin mode and does not require an Oracle Client installation.

Related MCP server: index-valuation

Installation

Run in PowerShell:

Set-Location 'D:\1.Project\19.CodexProject\9.MCP'
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e '.[dev]'

Copy .env.example to .env and fill in the real configuration. A runnable .env has already been created on this machine; this file is excluded by .gitignore and will not be committed to the repository.

Local stdio Mode

When started manually, the process waits for the MCP client to send messages from standard input:

.\.venv\Scripts\python.exe -m index_mcp.run_stdio

Codex uses a project-level or user-level config.toml. The following configuration makes Codex launch the local service directly:

[mcp_servers.wind_index]
command = 'D:\1.Project\19.CodexProject\9.MCP\.venv\Scripts\python.exe'
args = ["-m", "index_mcp.run_stdio"]
cwd = 'D:\1.Project\19.CodexProject\9.MCP'
required = true
default_tools_approval_mode = "auto"

After saving the configuration, restart Codex and check wind_index in /mcp. The official Codex documentation states that its desktop client, CLI, and IDE extension share MCP configuration and support both stdio and Streamable HTTP: Codex MCP documentation.

LAN HTTP Mode

Start the service:

Set-Location 'D:\1.Project\19.CodexProject\9.MCP'
.\.venv\Scripts\python.exe -m index_mcp.run_http

Current configuration:

• Local address: http://127.0.0.1:8765/mcp

• LAN address: http://172.18.3.114:8765/mcp

• Health check: http://172.18.3.114:8765/health

• The MCP endpoint must carry Authorization: Bearer <MCP_API_KEY>;

• /health requires no API Key and only returns {"status":"ok"}.

If the Windows firewall blocks LAN connections, open the port for the local subnet only from an elevated PowerShell:

New-NetFirewallRule -DisplayName 'WIND Index MCP 8765' `
  -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8765 `
  -RemoteAddress LocalSubnet

Do not map port 8765 directly to the public internet. When used across untrusted networks, enable HTTPS on a front proxy and upgrade to OAuth.

Codex Connecting to the LAN Service

First set an environment variable on the machine running Codex, whose value is the MCP_API_KEY from the server-side .env:

$env:WIND_INDEX_MCP_API_KEY = '<从服务端安全复制 API Key>'

Then configure it in the Codex config.toml:

[mcp_servers.wind_index_lan]
url = "http://172.18.3.114:8765/mcp"
bearer_token_env_var = "WIND_INDEX_MCP_API_KEY"
required = true
default_tools_approval_mode = "auto"

The official configuration option bearer_token_env_var reads the Bearer Token from an environment variable, avoiding writing the secret directly into config.toml. Other MCP clients that support Streamable HTTP can simply use the same URL and set the same Authorization request header.

Verification

Run the automated tests:

.\.venv\Scripts\python.exe -m pytest

Verify the stdio end-to-end call:

.\.venv\Scripts\python.exe .\scripts\smoke_test.py stdio

After the HTTP service is started, verify it in another PowerShell window:

.\.venv\Scripts\python.exe .\scripts\smoke_test.py http

Configuration Options

If DHCP changes the server's LAN IP, update both MCP_ALLOWED_HOSTS in .env and the client URL.

API Key Rotation

Generate a new key:

.\.venv\Scripts\python.exe -c "import secrets; print(secrets.token_urlsafe(48))"

Write the output to MCP_API_KEY in the server-side .env, restart the HTTP service, and then update the environment variables on each client. Do not commit the key to Git, chat logs, or logs.

Extending to Other Tables

Create a dedicated domain module for each new table or each group of closely related queries:

src/index_mcp/domains/<domain>/
├─ models.py
├─ repository.py
├─ service.py
└─ tools.py

The Repository layer may only hold fixed, parameterized read-only SQL; the Service layer handles input normalization and business boundaries; the Tools layer handles the MCP contract. Registering a new tool in server.py reuses the existing connection pool, authentication, logging, and dual-transport entry points.

Security Notes

• .env and .venv are ignored by Git;

• stdio logs are written only to stderr and do not pollute the MCP protocol stream;

• HTTP uses a Bearer API Key and Host allowlist;

• CORS is disabled by default;

• API Key over HTTP is only suitable for trusted LANs; network eavesdroppers can still intercept plaintext traffic;

• The database account should keep minimal read-only privileges on the Oracle side.