Mopsfin Taiwan Stock MCP Server

A public, read-only, database-free MCP server for Taiwan company financial data. The service is implemented with Next.js 16 App Router and the MCP TypeScript SDK v2, exposing seven tools over Stateless Streamable HTTP at /api/mcp; every financial query accesses MOPS Financial Comparison E-point directly.

This is not an official Taiwan Stock Exchange MCP server, nor does it constitute investment advice.

Architecture

LLM / MCP client
       │ Streamable HTTP
       ▼
Next.js /api/mcp on Vercel
       │ 固定 allowlist endpoint、form-urlencoded、無 cookie
       ▼
mopsfin.twse.com.tw
       │
       ├─ JSON → periods + series
       └─ HTML → 展開 rowspan/colspan 的二維 tables

• No database, Redis, or legacy HTTP+SSE transport.

• Financial data is not cached; only the dynamic catalog parsed from the homepage is cached in a single Vercel instance's memory for 5 minutes.

• Upstream URLs are fully fixed; tool arguments cannot supply URLs, so no arbitrary proxy/SSRF is possible.

• Upstream timeout is 20 seconds; network errors, 429, and 5xx are retried once, other 4xx are not retried.

• Mopsfin cookies are not retained or forwarded.

• The latest report probes up to 12 quarters backward from the last completed quarter and verifies the response period to avoid the source site silently falling back to another quarter.

• Vercel uses Node.js 24.x, Tokyo hnd1, 60-second function duration, and Fluid Compute.

Related MCP server: polygon-mcp

MCP Tools

Each tool has strict Zod input/output schemas and returns a short content summary plus full structuredContent. Tool annotations mark them as read-only, non-destructive, idempotent, and free of open-world side effects.

LLMs can obtain interpretive data from three layers: the server instructions in MCP initialize explain the overall data scope and calling order; tools/list provides purpose and caliber for the seven tools and every input/output field; list_catalog's officialGuidance and each metric's guidance provide formulas, value bases, applicable industry types, and caveats. The warnings in actual query results further carry filing frequency, single-quarter / cumulative, missing values, averages, or pagination warnings directly relevant to the current query.

When the code is unknown, call find_companies or list_catalog first. The family in list_catalog maps as follows:

Trends default to the most recent 12 quarters, adjustable with start_period, end_period, or history: "all". Large HTML tables are paginated with offset and limit, defaulting to 100 rows with a maximum of 500 rows. Period format is YYYYQn.

Company metrics can include the industry average and a simple average of selected companies via include_industry_average and include_company_average; financial institution metrics can include the corresponding financial industry average and a simple average of selected institutions via include_industry_average and include_institution_average. These averages are all computed by Mopsfin and are not market-capitalization weighted.

When answering data questions, at least preserve unit, the actual periods/period, the query basis, and warnings. null, NO_DATA, or a missing quarter may indicate not applicable, not yet filed, or not required for that market, and must not be rewritten as 0.

Local Development

Requirements: Node.js 24, npm 11.

npm install
npm run dev

Service:

• Homepage: http://localhost:3000/

• MCP: http://localhost:3000/api/mcp

• Health check: http://localhost:3000/api/health

The health check does not call Mopsfin, to avoid monitoring traffic becoming a fixed query load on the source site.

You can verify with the official MCP Inspector or the bundled client:

npm run test:client
# 或指定 Preview URL
npm run test:client -- https://your-preview.vercel.app/api/mcp

MCP client configuration example:

{
  "mcpServers": {
    "mopsfin": {
      "url": "https://your-domain.example/api/mcp"
    }
  }
}

Using with ChatGPT

ChatGPT requires a reachable public HTTPS /api/mcp URL; local localhost cannot be handed directly to remote ChatGPT.

1. Deploy to Vercel first and obtain https://<your-domain>/api/mcp.

2. In ChatGPT, enable Settings → Security and login → Developer mode.

3. Go to ChatGPT Plugins and press the plus sign to add a new connection.

4. Enter a name, e.g. Mopsfin Taiwan Stocks, and set the Connection URL to the full https://<your-domain>/api/mcp.

5. After creation, confirm ChatGPT can recognize the seven tools.

6. Start a new conversation, add this MCP connection from the tools menu, then ask about Taiwan stocks directly in natural language.

Whether Developer mode is available depends on the account plan and workspace policy. See the official OpenAI connection guide for details.

Example questions:

• "Look up TSMC's operating revenue for the last 12 quarters, organize it into a table, and point out the trend."

• "Compare TSMC and MediaTek's ROE over the last 8 quarters."

• "List the main items of TSMC's 2025Q4 balance sheet."

• "Compare the revenue trend of the semiconductor industry over the last 12 quarters."

• "Look up the most recent available banking capital adequacy ratio for Bank of Taiwan."

Verification

npm run lint
npm run type-check
npm test
npm run build

General tests use only fixed fixtures, covering 53 compareItem categories, six endpoint families, missing values, negative numbers, percentages, multiple companies, HTML merged cells, pagination, timeout, 429, 5xx, wrong quarters, and MCP initialize/tools/list/tools/call.

Live contract tests are skipped by default and only query the source site when explicitly set:

npm run test:live

Do not schedule live tests as periodic CI, to avoid creating a fixed query load on Mopsfin.

Deploying to Vercel

1. Import the repository into Vercel.

2. Use npm run build as the build command; Vercel will run npm install based on package-lock.json.

3. package.json already pins Node.js 24.x; vercel.json already enables Fluid Compute.

4. After deployment, verify with npm run test:client -- https://<preview>/api/mcp.

5. Set appropriate rules in the Vercel Firewall depending on public traffic; the application itself does not create a cross-instance rate-limit database.

Suggested Preview acceptance checks: TSMC revenue for the last 12 quarters, TSMC vs. MediaTek ROE, balance sheet for a specified quarter, semiconductor industry trend, Bank of Taiwan capital adequacy ratio, and TSMC financial statement notes.

Error Codes

• INVALID_ARGUMENT

• NOT_FOUND

• NO_DATA

• UPSTREAM_TIMEOUT

• UPSTREAM_RATE_LIMITED

• UPSTREAM_BAD_RESPONSE

Filing quarters differ by market: listed / OTC companies usually have Q1–Q4, emerging and public companies may only have Q2/Q4, and some companies only file annually. NO_DATA does not necessarily mean the company does not exist.

Data Source, Updates, and Terms of Use

The sole data source is Mopsfin. Per its website terms of use, the site data is updated once daily and may lag filings by about one day; this service does not use test fixtures as production data or fallback.

Before public launch, the project owner must independently confirm TWSE/Mopsfin's authorization for public proxying, redistribution, and usage frequency. The website terms' description of data scope and update frequency does not constitute an explicit grant of redistribution rights. Users should also use the original filings on the MOPS public information site as the final check.

Key References

• OpenAI: Build an MCP server

• Vercel: MCP for Next.js

• Next.js 16 upgrade guide

• Vercel Node.js versions

• Vercel Fluid Compute