FinanceMCP: A Multi-Source Financial Data MCP Server for Claude and Cursor

The gap FinanceMCP fills between an LLM and a market data vendor

A language model cannot query Tushare. It has no token, no HTTP client, and no idea that A-share fundamentals, Hong Kong listings, macro indicators and crypto tickers live behind different APIs with different authentication schemes. FinanceMCP exists to close that gap: it is a Model Context Protocol server that exposes financial data as callable tools, so a client such as Claude, Cursor, Codex or Trae can ask for a stock quote the same way it asks for a file read.

The target user is narrow and specific. You need an MCP-capable client, a Node.js 20 or newer runtime, and at least one data vendor account. The README lists Tushare Pro tokens, Qveris API keys and Twingly API keys as the credentialled sources, while the Binance public API, Baidu news search and the local system clock need no configuration at all. If your work is entirely US equities with no Chinese market exposure, the Tushare-centric design buys you little.

The project also positions itself as a data layer underneath FinNote, a document system built with MarkiNote. That matters less for evaluation than the boundary it reveals: FinanceMCP returns structured data and source metadata, not analysis. The reasoning stays in the client.

How the router picks a data source per request

The core mechanism is a router that sits in front of four providers. The README describes the default priority as tushare, twingly, qveris, binance, and notes that a request can override it with the X-Finance-Source-Priority header. Unknown entries are ignored, duplicates are deduplicated, and omitted sources are appended in default order. That last rule is the one worth remembering: you cannot accidentally exclude Binance by listing only two providers.

Credentials arrive per request over HTTP, not per process. The headers are X-Tushare-Token, X-Qveris-Api-Key and X-Twingly-Api-Key. The README states that HTTP keys are isolated through AsyncLocalStorage and that logs are masked, which is the kind of claim you should verify against src/ before putting a shared deployment in front of untrusted clients.

Fallback is the second half of the design. When a preferred source does not cover an endpoint, times out, or hits a rate limit, the router tries the next one. The README is careful to distinguish this from an empty result: a normal empty response does not trigger a repeat request. Every response carries a source label, and when a fallback happened you also get the full route, in the shape of "数据来源: Tushare" followed by a route line showing which provider failed and which succeeded.

Qveris is treated differently from the rest. It runs Discover, Inspect, Probe and Call internally, and the README states that at most one potentially billable Call is executed per MCP request. That cap is a deliberate cost control, and it is the detail to check if you are evaluating Qveris as a replacement for Tushare rather than a supplement.

Installing finance-mcp and running a first stdio session

Installation goes through npm. The package name is finance-mcp, and the published bin entries are finance-mcp for stdio and finance-mcp-http for the HTTP server. Node.js 20 or newer is required, per the engines field in package.json.

npm install -g finance-mcp

After a global install, the finance-mcp command starts the stdio server. For a local checkout the equivalent scripts are npm run start:stdio and npm run start:http, both of which build first through the prepare script.

Credentials come from environment variables. Copy .env.example to .env and fill in the token; the template ships with TUSHARE_TOKEN as the only uncommented data source key, and Qveris and Twingly commented out so that no request is made to them.

TUSHARE_TOKEN=YOUR_REAL_TUSHARE_TOKEN_HERE
PORT=3000
MCP_HTTP_HOST=127.0.0.1

The README points to the Tushare registration page and the official token guide for obtaining the value; the template does not contain a working token. Note the .env.example comments: lines beginning with # are ignored by dotenv, and the option descriptions sit on those comment lines.

To confirm what the server actually exposes before wiring it into a client, the repository ships an inspector script that launches the MCP Inspector against the built stdio entry point.

npm run inspector

The important behaviour to observe is that tools/list is trimmed to the credentials present in the request. With only TUSHARE_TOKEN set, the catalogue shows the tools Tushare covers. Add a Twingly key and the two news tools appear. With no credentials at all you get public sources and local tools only. The README states that tools/call enforces the same check, so an agent cannot call a provider the current request has no key for.

The Dockerfile is a two-stage build on node:lts-alpine that runs as a non-root appuser, exposes port 3000, and defaults to node build/httpServer.js. It sets MCP_HTTP_HOST to 0.0.0.0, which is the opposite of the .env.example default of 127.0.0.1. If you deploy the image, that difference is the one to think about.

Where FinanceMCP breaks down

The most concrete limitation is stated at the top of the README in a warning block: the public hosted service is suspended. The original domain expired, and there is no official online endpoint at the time of writing. The repository says a replacement domain may come later and that announcements will appear in the repo. Everything below that line (the npm package, local stdio, self-hosting) is unaffected, but anyone who wanted to point a client at a URL and skip the setup should stop here.

Credential trimming cuts both ways. It is a real safety property, and it is also a source of confusing failures. An agent that worked yesterday with a Tushare token will find the Qveris-backed tools missing today if the token was removed, and the tool list is the only place that shows it. There is no documented error explaining an absent tool, because absence is not an error.

News coverage has an explicit boundary. FinanceMCP returns titles, sources, timestamps, article and site identifiers, URLs, language and region, section and deduplication metadata for Twingly results. The README states plainly that it does not return or persist article full text. Any pipeline expecting to summarise article bodies must fetch the URL itself and handle the licensing question separately.

Access tiers are the other practical wall. Tushare interfaces have per-endpoint point thresholds and rate limits, and the README directs readers to the interface documentation and the points permission page rather than promising uniform access. The student verification path is mentioned as granting 2000 points, with 5000 for verified teachers, but the README also says the current process requires school and personal profile completion, joining a user group, and submitting documentation to an administrator. That is a manual process, not an API call.

FinanceMCP versus a plain SDK or a general web-search tool

The obvious alternative is skipping MCP entirely and calling the Tushare and Binance REST APIs from your own code. That gives you complete control over retries, caching, and response shaping, and it removes a Node.js runtime from the picture. What you lose is the router. The fallback logic, the source labelling, the per-request credential isolation and the tools/list trimming all have to be rebuilt, and rebuilding them correctly is more work than it sounds.

The other alternative is a general-purpose web search or browsing tool attached to the same agent. That approach handles news and handles obscure instruments, but it returns prose and links, not typed fields. A question about a specific indicator or a fund holding is answered differently: the search tool gives you a page to read, FinanceMCP gives you a structured result with a named source. For quantitative work the structured path is the one that composes.

There is also the option of running only the pieces you need. Binance public data and Baidu news require no credentials, so a client configured with no tokens at all still gets crypto quotes and public news search plus the local clock tool. That is a legitimate low-commitment way to try the server before registering for anything.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-07. Releases are frequent: v4.11.0 on 2026-08-26, v4.11.1 on 2026-08-28, and v4.11.2 on 2026-09-04. The v4.11.2 notes describe hardening of Twingly news routing around parameter validation, request size limits, source fallback and dynamic tool schemas, plus masking of sensitive request headers. The same note states that the 19 tool names and their main calling conventions are unchanged, which is the compatibility promise to hold onto when upgrading.

Version 4.11.x is a patch series, so the upgrade cost between them is low by the project's own description. The larger risk sits in the data providers: Tushare point thresholds, Qveris credit consumption and Twingly quotas can change outside this repository, and a router that silently falls back will keep answering with a different source rather than failing. Watch the source label in responses, not just the payload.

The licence is MIT, declared in the LICENSE file and in package.json metadata. That is permissive for commercial use and modification, but it says nothing about the data you pull through the server. Tushare, Qveris, Twingly and any news source carry their own terms, and redistributing vendor data is a separate question from redistributing this code. The README does not address data redistribution; treat that as unresolved and check each vendor's agreement.

The optional finance-cache-gateway is a separate process on its own port with its own config, and the README states it does not modify existing MCP tools, stdio, or the /mcp interface. If you never start it, nothing changes. That separation is the right call, and it means the gateway can be ignored entirely during an initial evaluation.

Editorial conclusion

Adopt FinanceMCP if your agent needs Chinese market fundamentals from Tushare plus crypto quotes from Binance behind one MCP interface, and you are willing to run it yourself with your own tokens. Skip it if you need a hosted endpoint, since the README states the public service is suspended, or if you want article full text from news search, which the project explicitly does not return. Before wiring it into a workflow, run the stdio server with only TUSHARE_TOKEN set and call tools/list, because the tool catalogue is trimmed to the credentials in the request.

Frequently asked questions

Official sources

1. guangxiangdebizi/FinanceMCP on GitHub
2. Issues
3. License: MIT
4. README
5. Releases