Model or dataset
guangxiangdebizi/FinanceMCP avatar
guangxiangdebizi/FinanceMCP

FinanceMCP: a routing layer for Tushare, Qveris, Twingly and Binance behind 19 MCP tools

A finance-focused MCP server that integrates the Tushare API and Binance API to give language models (like Claude) comprehensive access to real-time financial data, supporting multi-dimensional analysis of stocks, funds, bonds, macroeconomic indicators, stablecoins and cryptocurrencies, including financial data queries, financial news queries, and National Bureau of Statistics data queries.

872 stars144 forksTypeScriptMIT

At a glance

What is it?
FinanceMCP is a TypeScript MCP server that exposes 19 stable tools over stdio or Streamable HTTP and routes each request across several financial data providers. The interesting part is the routing and credential handling, not the tool count.
Who is it for?
Adopt FinanceMCP if you already hold a Tushare token or want a single MCP endpoint that mixes A-share, macro and crypto data for a Chinese-market workflow, and if you are willing to run it yourself now that the hosted endpoint is gone. Do not adopt it if you need a managed service, if you have no Tushare account and no appetite for the points system, or if your agent must work without any provider key at all.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 6 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • guangxiangdebizi/FinanceMCP872 ★ · +207
Star history
Repository2026-09-122026-11-15
guangxiangdebizi/FinanceMCP665872

207 Stars in the last 64 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The gap FinanceMCP fills: one MCP surface over several paid data vendors

A language model that needs Chinese equity data, macro indicators and crypto prices normally means three integrations, three credential formats and three response shapes. FinanceMCP collapses that into one MCP server exposing 19 tools, with the provider choice made per request rather than baked into the tool signature. The README states the project keeps existing tool names and parameters intact and moves data source selection into the request context. That matters if you already have prompts or agent code pinned to a tool name. The intended audience is narrow but real: developers building agents for Chinese-market research, where Tushare is the common source for A-shares, funds, bonds and macro series, and where a news feed and a crypto feed are wanted alongside it. It is also positioned as the data layer under FinNote, a document system built with MarkiNote, which the README says calls FinanceMCP over HTTP or MCP.

Routing, fallback and the priority header

The router sits between the MCP client and the providers. The default order is tushare,twingly,qveris,binance, and a request can override it with the X-Finance-Source-Priority header. The README gives this example value: twingly,qveris,tushare,binance. Unknown entries are ignored, duplicates are removed, and anything you leave out is appended in the default order. Fallback triggers on an uncovered interface, a timeout, a rate limit or an outright failure. Empty results do not trigger a retry, which is the right call and worth noting because a naive retry-on-empty would multiply billable calls. Every response carries the source that actually served it, and when a fallback happened the full route is returned too. The README shows the shape: a line naming the source, then a route line reading Qveris then Tushare with the reason in parentheses. That traceability is the strongest part of the design. Without it, a silent downgrade from a paid provider to a public one would be invisible to the agent and to whoever reads the output later.

Credentials move per request, and the tool list shrinks to match

There are two credential paths. Under stdio you set environment variables: TUSHARE_TOKEN, QVERIS_API_KEY, TWINGLY_API_KEY. Over HTTP you send X-Tushare-Token, X-Qveris-Api-Key and X-Twingly-Api-Key instead. Binance needs nothing, since it uses the public spot REST API, and the finance_news tool uses public Baidu news search with no key. The HTTP path is where the design gets interesting. Keys are isolated per request through AsyncLocalStorage, and the README says logs are redacted. More unusually, tools/list is filtered by the credentials present on the request: send only a Twingly key and you see the two news tools, send only a Qveris key and you see the tools that adapter covers, send several and you see the union. With no credentials you get public sources and local tools only. tools/call applies the same check. This prevents an agent from selecting a tool it cannot actually use in that request, which is a failure mode that otherwise shows up as an opaque provider error. The cost is that the tool catalogue is no longer a stable object you can cache across sessions.

Running it: stdio for local clients, HTTP for shared deployments

The package is published on npm as finance-mcp and requires Node.js 20 or newer. The README documents the two transports but the cleaned excerpt does not include the literal launch command, so check the Quick Start section of the repository before wiring it into a client. What is documented is the configuration surface: for stdio, the three environment variables above; for Streamable HTTP, the four headers, three for keys plus X-Finance-Source-Priority. Tushare tokens come from the account page after registration, and the README points to the official token guide. Qveris keys come from its dashboard and the REST API contract is linked separately. Twingly keys come from its dashboard. A separate optional process, finance-cache-gateway, is documented for sharing prompt and KV-cache routing across Trae, Cursor, Claude Code and Codex. It runs on its own port with its own config and does not alter the MCP tools or the /mcp interface when unused.

The hosted endpoint is gone, and the points system is the real gate

The README carries a warning that the public hosted service is stopped: the domain expired and there is no official online endpoint at the time of writing, with a possible new address announced later. The npm package, local stdio use and self-hosting are unaffected. So this is a self-hosted tool now, and anyone evaluating it should plan for that. The second constraint is Tushare itself. Its interfaces sit behind a points system with different thresholds and rate limits per interface, and the README directs you to the per-interface documentation and the permissions page rather than promising blanket access. Student verification is described as granting 2000 points, with teachers at 5000, subject to the official process. That is a strong incentive for academic users and a real friction point for everyone else. If your workflow depends on a specific Tushare interface above your tier, the router will not rescue you: the fallback chain only helps when another provider covers the same data, and for many A-share datasets it will not.

Qveris is metered, and the router is built to respect that

Qveris is optional and only called when its key is present. The README is explicit that without X-Qveris-Api-Key or QVERIS_API_KEY it is not called and no credits are consumed. When it is used, the adapter runs a Discover, Inspect, Probe, Call sequence and executes at most one potentially billable Call per MCP request. That single-call ceiling is the constraint that shapes everything else: a broad question from an agent cannot fan out into a dozen billable probes. It also means the router has to decide before calling, which is why the priority header and the credential-based tool filtering exist. If you want Qveris to be the primary source, set the priority header accordingly rather than relying on fallback, because fallback only fires after the earlier provider fails or does not cover the interface.

Twingly returns metadata, not article text

The global news path through Twingly is deliberately limited. The README states FinanceMCP returns only title, source, time, article and site identifiers, URL, language and region, section and deduplication metadata. It does not return or persist full article text. For an agent that needs to summarize or quote an article, that is a hard boundary: you get a pointer and have to fetch the body yourself, under whatever terms the publisher sets. The design is defensible from a licensing standpoint, since redistributing full text through an MCP server would raise questions the MIT licence on this repository does not answer. Just do not expect the news tools to behave like a corpus. The public Baidu news path behind finance_news has no key requirement, and the README does not describe its result shape in the same detail.

What you give up compared with a single-vendor client

The obvious alternative is calling Tushare directly from your own code, or using the vendor SDKs for each source. That gives you the full interface surface, your own caching, and no dependency on a router's notion of which interface is covered. The difference in approach is sharp: FinanceMCP trades breadth and control for a uniform MCP tool surface and automatic fallback, and it decides coverage for you. A direct Tushare client will reach interfaces the router may not have mapped, and it will not silently substitute a different provider. The counter-argument is operational. If your agent already speaks MCP, adding a data router is a config change, whereas writing three provider clients with retry, rate-limit handling and source attribution is a project. The honest framing is that FinanceMCP is a convenience layer, and convenience layers hide decisions. The source and route lines in each response are what make those decisions auditable, so read them rather than discarding them.

Maintenance, versioning and the licence

The project is active, with v4.11.2 released on 2026-09-04 and v4.11.1 and v4.11.0 in the weeks before. The v4.11.2 notes describe hardening of the Twingly news route: parameter validation, request size limits, data source fallback, dynamic tool schemas, and redaction of sensitive request headers. The release note states that the 19 tool names and the main calling conventions are unchanged, which is the property that matters most if you have prompts pinned to them. The repository is MIT licensed, which permits commercial use and modification, but the licence covers this code only. Your Tushare, Qveris and Twingly accounts carry their own terms, and the points and credit systems described above are commercial constraints the MIT licence does not touch. Nothing here is legal advice; read the provider agreements before shipping anything that resells their data.

Editorial conclusion

Adopt FinanceMCP if you already hold a Tushare token or want a single MCP endpoint that mixes A-share, macro and crypto data for a Chinese-market workflow, and if you are willing to run it yourself now that the hosted endpoint is gone. Do not adopt it if you need a managed service, if you have no Tushare account and no appetite for the points system, or if your agent must work without any provider key at all. Before committing, verify three things: that the specific Tushare interfaces you need are covered at your points tier, that your MCP client passes custom headers so the HTTP credential path works, and that the 19 tool names and schemas in v4.11.2 match what your prompts already assume.

Frequently asked questions

What is FinanceMCP and how many tools does it expose?

FinanceMCP is a TypeScript Model Context Protocol server that gives language models financial data across Tushare, optional Qveris, Twingly news, Binance and public sources. It advertises nineteen stable tools covering stocks, funds, bonds, macro figures, news, technical indicators and multi-market quotes, over stdio or Streamable HTTP.

Which FinanceMCP data sources need an API key?

Three. Tushare Pro needs a token, Qveris needs an API key, and Twingly News Search needs an API key. Binance needs no account or trading permission because only public kline interfaces are called, Baidu News needs no developer credentials, and the local system clock exists only to serve current_timestamp.

How does FinanceMCP choose a data source, and when does it fall back?

Sources are tried in the order tushare, twingly, qveris, binance, which a request can reorder with X-Finance-Source-Priority. If the preferred source does not cover the request or the call fails, the next source is tried, but a normal empty result does not trigger another request. A caller parameter that fails validation does not fall back to a semantically different source.

Does using FinanceMCP cost anything?

Only through the optional Qveris extension, which Discover and Inspect for free but may charge per Call, and which the server limits to at most one potentially billable Call per MCP request. Without a Qveris key it is not called and no credits are consumed. Tushare issues points, with 2000 for verified university students and 5000 for teachers, and per-interface thresholds differ.

Can I use the hosted FinanceMCP service?

Not at the moment. The page states the public hosted service is temporarily stopped because the original domain has expired, that there is no official online experience or hosted endpoint, and that a new domain may follow. The npm package, local stdio use and self-deployment are unaffected, so the container build with its own environment variables is the supported route.

Official sources

  1. guangxiangdebizi/FinanceMCP on GitHub
  2. Issues
  3. License: MIT
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/guangxiangdebizi-financemcp.svg)](https://hysenlabs.com/projects/guangxiangdebizi-financemcp)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/guangxiangdebizi-financemcp.svg)](https://hysenlabs.com/projects/guangxiangdebizi-financemcp)

Was this useful?