@cyanheads/finnhub-mcp-server 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/AGENTS.md +376 -0
  2. package/CLAUDE.md +376 -0
  3. package/Dockerfile +121 -0
  4. package/LICENSE +201 -0
  5. package/README.md +314 -0
  6. package/changelog/0.1.x/0.1.0.md +22 -0
  7. package/changelog/template.md +127 -0
  8. package/dist/config/server-config.d.ts +25 -0
  9. package/dist/config/server-config.d.ts.map +1 -0
  10. package/dist/config/server-config.js +37 -0
  11. package/dist/config/server-config.js.map +1 -0
  12. package/dist/index.d.ts +8 -0
  13. package/dist/index.d.ts.map +1 -0
  14. package/dist/index.js +21 -0
  15. package/dist/index.js.map +1 -0
  16. package/dist/mcp-server/resources/definitions/index.d.ts +12 -0
  17. package/dist/mcp-server/resources/definitions/index.d.ts.map +1 -0
  18. package/dist/mcp-server/resources/definitions/index.js +8 -0
  19. package/dist/mcp-server/resources/definitions/index.js.map +1 -0
  20. package/dist/mcp-server/resources/definitions/news-categories.resource.d.ts +16 -0
  21. package/dist/mcp-server/resources/definitions/news-categories.resource.d.ts.map +1 -0
  22. package/dist/mcp-server/resources/definitions/news-categories.resource.js +45 -0
  23. package/dist/mcp-server/resources/definitions/news-categories.resource.js.map +1 -0
  24. package/dist/mcp-server/tools/definitions/get-company.tool.d.ts +51 -0
  25. package/dist/mcp-server/tools/definitions/get-company.tool.d.ts.map +1 -0
  26. package/dist/mcp-server/tools/definitions/get-company.tool.js +191 -0
  27. package/dist/mcp-server/tools/definitions/get-company.tool.js.map +1 -0
  28. package/dist/mcp-server/tools/definitions/get-earnings.tool.d.ts +59 -0
  29. package/dist/mcp-server/tools/definitions/get-earnings.tool.d.ts.map +1 -0
  30. package/dist/mcp-server/tools/definitions/get-earnings.tool.js +201 -0
  31. package/dist/mcp-server/tools/definitions/get-earnings.tool.js.map +1 -0
  32. package/dist/mcp-server/tools/definitions/get-news.tool.d.ts +55 -0
  33. package/dist/mcp-server/tools/definitions/get-news.tool.d.ts.map +1 -0
  34. package/dist/mcp-server/tools/definitions/get-news.tool.js +160 -0
  35. package/dist/mcp-server/tools/definitions/get-news.tool.js.map +1 -0
  36. package/dist/mcp-server/tools/definitions/get-quote.tool.d.ts +35 -0
  37. package/dist/mcp-server/tools/definitions/get-quote.tool.d.ts.map +1 -0
  38. package/dist/mcp-server/tools/definitions/get-quote.tool.js +132 -0
  39. package/dist/mcp-server/tools/definitions/get-quote.tool.js.map +1 -0
  40. package/dist/mcp-server/tools/definitions/get-recommendations.tool.d.ts +38 -0
  41. package/dist/mcp-server/tools/definitions/get-recommendations.tool.d.ts.map +1 -0
  42. package/dist/mcp-server/tools/definitions/get-recommendations.tool.js +110 -0
  43. package/dist/mcp-server/tools/definitions/get-recommendations.tool.js.map +1 -0
  44. package/dist/mcp-server/tools/definitions/index.d.ts +209 -0
  45. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -0
  46. package/dist/mcp-server/tools/definitions/index.js +20 -0
  47. package/dist/mcp-server/tools/definitions/index.js.map +1 -0
  48. package/dist/mcp-server/tools/definitions/search-symbols.tool.d.ts +26 -0
  49. package/dist/mcp-server/tools/definitions/search-symbols.tool.d.ts.map +1 -0
  50. package/dist/mcp-server/tools/definitions/search-symbols.tool.js +101 -0
  51. package/dist/mcp-server/tools/definitions/search-symbols.tool.js.map +1 -0
  52. package/dist/services/finnhub/finnhub-service.d.ts +77 -0
  53. package/dist/services/finnhub/finnhub-service.d.ts.map +1 -0
  54. package/dist/services/finnhub/finnhub-service.js +148 -0
  55. package/dist/services/finnhub/finnhub-service.js.map +1 -0
  56. package/dist/services/finnhub/types.d.ts +147 -0
  57. package/dist/services/finnhub/types.d.ts.map +1 -0
  58. package/dist/services/finnhub/types.js +9 -0
  59. package/dist/services/finnhub/types.js.map +1 -0
  60. package/package.json +85 -0
  61. package/server.json +125 -0
@@ -0,0 +1,148 @@
1
+ /**
2
+ * @fileoverview FinnhubService — the single authenticated, rate-aware,
3
+ * status-classifying HTTP client for the Finnhub REST API. One typed method per
4
+ * upstream endpoint the tool surface needs. Owns auth (the `token` query param),
5
+ * resilience (`withRetry` around the full fetch+parse pipeline via
6
+ * `fetchWithTimeout`), and the status classification that gives every tool
7
+ * identical, correct error semantics.
8
+ * @module services/finnhub/finnhub-service
9
+ */
10
+ import { configurationError, JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
11
+ import { fetchWithTimeout, withRetry } from '@cyanheads/mcp-ts-core/utils';
12
+ import { getServerConfig } from '../../config/server-config.js';
13
+ /** Per-request timeout for a single Finnhub call. */
14
+ const REQUEST_TIMEOUT_MS = 10_000;
15
+ /**
16
+ * Retry backoff calibrated to a rate-limited upstream — the 60 req/min free-tier
17
+ * cap is the realistic failure mode under burst, so a ~1s base gives the window
18
+ * time to roll over.
19
+ */
20
+ const RETRY_BASE_DELAY_MS = 1_000;
21
+ /**
22
+ * Authenticated client for the Finnhub REST API. Initialized once in
23
+ * `createApp`'s `setup()` and accessed via {@link getFinnhubService}.
24
+ */
25
+ export class FinnhubService {
26
+ baseUrl;
27
+ apiKey;
28
+ constructor() {
29
+ const serverConfig = getServerConfig();
30
+ this.baseUrl = serverConfig.baseUrl.replace(/\/$/, '');
31
+ this.apiKey = serverConfig.apiKey;
32
+ }
33
+ /** `GET /search?q={query}` — resolve a name/ticker fragment to symbols. */
34
+ search(query, ctx) {
35
+ return this.request('/search', { q: query }, 'search', ctx);
36
+ }
37
+ /** `GET /quote?symbol={symbol}` — real-time price snapshot. */
38
+ quote(symbol, ctx) {
39
+ return this.request('/quote', { symbol }, 'quote', ctx);
40
+ }
41
+ /** `GET /stock/market-status?exchange={exchange}` — live market-open flag. */
42
+ marketStatus(exchange, ctx) {
43
+ return this.request('/stock/market-status', { exchange }, 'marketStatus', ctx);
44
+ }
45
+ /** `GET /stock/profile2?symbol={symbol}` — company profile (`{}` if unknown). */
46
+ profile(symbol, ctx) {
47
+ return this.request('/stock/profile2', { symbol }, 'profile', ctx);
48
+ }
49
+ /** `GET /stock/metric?symbol={symbol}&metric=all` — fundamentals (~100 keys). */
50
+ metrics(symbol, ctx) {
51
+ return this.request('/stock/metric', { symbol, metric: 'all' }, 'metrics', ctx);
52
+ }
53
+ /** `GET /stock/peers?symbol={symbol}` — sector peer symbols (includes the query). */
54
+ peers(symbol, ctx) {
55
+ return this.request('/stock/peers', { symbol }, 'peers', ctx);
56
+ }
57
+ /** `GET /stock/earnings?symbol={symbol}` — past quarters, newest first. */
58
+ earnings(symbol, ctx) {
59
+ return this.request('/stock/earnings', { symbol }, 'earnings', ctx);
60
+ }
61
+ /** `GET /calendar/earnings?from={from}&to={to}` — upcoming releases window. */
62
+ earningsCalendar(from, to, ctx) {
63
+ return this.request('/calendar/earnings', { from, to }, 'earningsCalendar', ctx);
64
+ }
65
+ /** `GET /company-news?symbol={symbol}&from={from}&to={to}`. */
66
+ companyNews(symbol, from, to, ctx) {
67
+ return this.request('/company-news', { symbol, from, to }, 'companyNews', ctx);
68
+ }
69
+ /** `GET /news?category={category}` — market-wide headlines. */
70
+ marketNews(category, ctx) {
71
+ return this.request('/news', { category }, 'marketNews', ctx);
72
+ }
73
+ /** `GET /stock/recommendation?symbol={symbol}` — analyst trends, empty if no coverage. */
74
+ recommendations(symbol, ctx) {
75
+ return this.request('/stock/recommendation', { symbol }, 'recommendations', ctx);
76
+ }
77
+ /**
78
+ * Core request pipeline: build the authenticated URL, fetch, and parse — all
79
+ * wrapped in `withRetry` so transient failures (429/5xx/network) back off and
80
+ * retry while deterministic failures (401/403) fail fast.
81
+ *
82
+ * `fetchWithTimeout` throws a classified `McpError` on any non-OK status and
83
+ * reduces URLs in errors/logs to origin + pathname, so the `token` query
84
+ * param never reaches a client or a log line. Its default status mapping
85
+ * matches the design for 403 (→ `Forbidden`), 429 (→ `RateLimited`), and 5xx
86
+ * (→ `ServiceUnavailable`); only 401 is re-keyed below from `Unauthorized` to
87
+ * `ConfigurationError` so a bad/missing key fails loud as misconfiguration
88
+ * rather than "no data".
89
+ */
90
+ request(path, params, operation, ctx) {
91
+ const url = new URL(`${this.baseUrl}${path}`);
92
+ for (const [key, value] of Object.entries(params)) {
93
+ url.searchParams.set(key, value);
94
+ }
95
+ url.searchParams.set('token', this.apiKey);
96
+ const signal = ctx.signal;
97
+ return withRetry(async () => {
98
+ try {
99
+ const response = await fetchWithTimeout(url.toString(), REQUEST_TIMEOUT_MS, ctx, {
100
+ headers: { Accept: 'application/json' },
101
+ ...(signal && { signal }),
102
+ });
103
+ return (await response.json());
104
+ }
105
+ catch (err) {
106
+ throw this.reclassify(err, operation, path);
107
+ }
108
+ }, {
109
+ operation: `FinnhubService.${operation}`,
110
+ context: ctx,
111
+ baseDelayMs: RETRY_BASE_DELAY_MS,
112
+ ...(signal && { signal }),
113
+ });
114
+ }
115
+ /**
116
+ * Re-key a thrown `McpError` so a 401 (which `fetchWithTimeout` classifies as
117
+ * `Unauthorized`) becomes a `ConfigurationError` — a bad/missing Finnhub key
118
+ * is a misconfiguration that should fail loud, not a per-request auth failure.
119
+ * Every other error passes through unchanged: `Forbidden` (403),
120
+ * `RateLimited` (429), and `ServiceUnavailable` (5xx/network) already match
121
+ * the design's classification table.
122
+ */
123
+ reclassify(err, operation, path) {
124
+ if (err instanceof McpError && err.code === JsonRpcErrorCode.Unauthorized) {
125
+ return configurationError('Finnhub rejected the API key (HTTP 401). Set a valid FINNHUB_API_KEY from https://finnhub.io/register.', { operation, path }, { cause: err });
126
+ }
127
+ return err;
128
+ }
129
+ }
130
+ // --- Init/accessor pattern ---
131
+ let _service;
132
+ /**
133
+ * Initialize the singleton. Called from `createApp`'s `setup()`. The
134
+ * `(config, storage)` signature matches the framework's `setup(core)` call
135
+ * convention; this service reads its own config via `getServerConfig()` and
136
+ * holds no tenant state, so neither is retained.
137
+ */
138
+ export function initFinnhubService(_config, _storage) {
139
+ _service = new FinnhubService();
140
+ }
141
+ /** Access the singleton. Throws if `setup()` did not initialize it. */
142
+ export function getFinnhubService() {
143
+ if (!_service) {
144
+ throw new Error('FinnhubService not initialized — call initFinnhubService() in setup()');
145
+ }
146
+ return _service;
147
+ }
148
+ //# sourceMappingURL=finnhub-service.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"finnhub-service.js","sourceRoot":"","sources":["../../../src/services/finnhub/finnhub-service.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,147 @@
1
+ /**
2
+ * @fileoverview Raw upstream response shapes for the Finnhub REST API (v1).
3
+ * One type per endpoint the service calls, mirroring the verified live payloads
4
+ * (probed 2026-06-13). Fields the free tier may omit are optional/nullable so
5
+ * normalization preserves absence as "unknown" rather than fabricating values.
6
+ * @module services/finnhub/types
7
+ */
8
+ /** A single match from `GET /search`. */
9
+ export interface FinnhubSearchMatch {
10
+ description: string;
11
+ displaySymbol: string;
12
+ symbol: string;
13
+ /** Security type, e.g. "Common Stock", "ETP". Finnhub returns "" when unknown. */
14
+ type: string;
15
+ }
16
+ /** `GET /search?q={query}`. */
17
+ export interface FinnhubSearchResponse {
18
+ count: number;
19
+ result: FinnhubSearchMatch[];
20
+ }
21
+ /**
22
+ * `GET /quote?symbol={symbol}`. An unknown US symbol returns the all-zero
23
+ * sentinel `{c:0, d:null, dp:null, h:0, l:0, o:0, pc:0, t:0}` at HTTP 200 —
24
+ * `d`/`dp` are null, `c`/`t` are zero.
25
+ */
26
+ export interface FinnhubQuote {
27
+ /** Current price. */
28
+ c: number;
29
+ /** Change vs. previous close. Null in the unknown-symbol sentinel. */
30
+ d: number | null;
31
+ /** Percent change vs. previous close. Null in the sentinel. */
32
+ dp: number | null;
33
+ /** Session high. */
34
+ h: number;
35
+ /** Session low. */
36
+ l: number;
37
+ /** Session open. */
38
+ o: number;
39
+ /** Previous close. */
40
+ pc: number;
41
+ /** Quote time, Unix epoch seconds. Zero in the sentinel. */
42
+ t: number;
43
+ }
44
+ /** `GET /stock/market-status?exchange={exchange}`. */
45
+ export interface FinnhubMarketStatus {
46
+ exchange: string;
47
+ holiday: string | null;
48
+ isOpen: boolean;
49
+ session: string | null;
50
+ t: number;
51
+ timezone: string;
52
+ }
53
+ /**
54
+ * `GET /stock/profile2?symbol={symbol}`. An unknown symbol returns `{}`, so
55
+ * every field is optional — presence of `name`/`ticker` distinguishes a real
56
+ * profile from the empty sentinel.
57
+ */
58
+ export interface FinnhubProfile {
59
+ country?: string;
60
+ currency?: string;
61
+ estimateCurrency?: string;
62
+ exchange?: string;
63
+ finnhubIndustry?: string;
64
+ floatingShare?: number;
65
+ ipo?: string;
66
+ logo?: string;
67
+ marketCapitalization?: number;
68
+ name?: string;
69
+ phone?: string;
70
+ shareOutstanding?: number;
71
+ ticker?: string;
72
+ weburl?: string;
73
+ }
74
+ /**
75
+ * `GET /stock/metric?symbol={symbol}&metric=all`. The `metric` object carries
76
+ * ~100 keys; only the curated subset surfaced by `finnhub_get_company` is typed
77
+ * here. Every value is optional — Finnhub omits metrics for thinly-covered
78
+ * names.
79
+ */
80
+ export interface FinnhubMetricResponse {
81
+ metric?: {
82
+ peTTM?: number;
83
+ epsTTM?: number;
84
+ '52WeekHigh'?: number;
85
+ '52WeekLow'?: number;
86
+ beta?: number;
87
+ currentDividendYieldTTM?: number;
88
+ netProfitMarginTTM?: number;
89
+ grossMarginTTM?: number;
90
+ revenueGrowthTTMYoy?: number;
91
+ roeTTM?: number;
92
+ [key: string]: number | string | undefined;
93
+ };
94
+ metricType?: string;
95
+ symbol?: string;
96
+ }
97
+ /** A single quarter from `GET /stock/earnings`. */
98
+ export interface FinnhubEarning {
99
+ actual: number | null;
100
+ estimate: number | null;
101
+ period: string;
102
+ quarter: number;
103
+ surprise: number | null;
104
+ surprisePercent: number | null;
105
+ symbol: string;
106
+ year: number;
107
+ }
108
+ /** A single entry from `GET /calendar/earnings`. */
109
+ export interface FinnhubEarningsCalendarEntry {
110
+ date: string;
111
+ epsActual: number | null;
112
+ epsEstimate: number | null;
113
+ /** "bmo" (before open) / "amc" (after close) / "" when unknown. */
114
+ hour: string;
115
+ quarter: number;
116
+ revenueActual: number | null;
117
+ revenueEstimate: number | null;
118
+ symbol: string;
119
+ year: number;
120
+ }
121
+ /** `GET /calendar/earnings?from={from}&to={to}`. */
122
+ export interface FinnhubEarningsCalendar {
123
+ earningsCalendar: FinnhubEarningsCalendarEntry[];
124
+ }
125
+ /** A single article from `GET /company-news` or `GET /news`. */
126
+ export interface FinnhubNewsArticle {
127
+ category?: string;
128
+ datetime: number;
129
+ headline: string;
130
+ id?: number;
131
+ image?: string;
132
+ related?: string;
133
+ source: string;
134
+ summary?: string;
135
+ url: string;
136
+ }
137
+ /** A single month from `GET /stock/recommendation`. */
138
+ export interface FinnhubRecommendation {
139
+ buy: number;
140
+ hold: number;
141
+ period: string;
142
+ sell: number;
143
+ strongBuy: number;
144
+ strongSell: number;
145
+ symbol: string;
146
+ }
147
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/finnhub/types.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,9 @@
1
+ /**
2
+ * @fileoverview Raw upstream response shapes for the Finnhub REST API (v1).
3
+ * One type per endpoint the service calls, mirroring the verified live payloads
4
+ * (probed 2026-06-13). Fields the free tier may omit are optional/nullable so
5
+ * normalization preserves absence as "unknown" rather than fabricating values.
6
+ * @module services/finnhub/types
7
+ */
8
+ export {};
9
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/finnhub/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}
package/package.json ADDED
@@ -0,0 +1,85 @@
1
+ {
2
+ "name": "@cyanheads/finnhub-mcp-server",
3
+ "version": "0.1.0",
4
+ "description": "Real-time US-equity quotes, company fundamentals, earnings, analyst trends, and financial news via Finnhub. STDIO or Streamable HTTP.",
5
+ "type": "module",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "bin": {
9
+ "finnhub-mcp-server": "dist/index.js"
10
+ },
11
+ "files": [
12
+ "changelog/",
13
+ "dist/",
14
+ "README.md",
15
+ "LICENSE",
16
+ "CLAUDE.md",
17
+ "AGENTS.md",
18
+ "Dockerfile",
19
+ "server.json"
20
+ ],
21
+ "scripts": {
22
+ "build": "bun run scripts/build.ts",
23
+ "rebuild": "bun run scripts/clean.ts && bun run scripts/build.ts",
24
+ "clean": "bun run scripts/clean.ts",
25
+ "devcheck": "bun run scripts/devcheck.ts",
26
+ "audit:refresh": "rm -f bun.lock && bun install && bun audit",
27
+ "tree": "bun run scripts/tree.ts",
28
+ "list-skills": "bun run scripts/list-skills.ts",
29
+ "format": "biome check --write .",
30
+ "format:unsafe": "biome check --write --unsafe .",
31
+ "lint:mcp": "bun run scripts/lint-mcp.ts",
32
+ "lint:packaging": "bun run scripts/lint-packaging.ts",
33
+ "bundle": "bun run build && npx -y @anthropic-ai/mcpb pack . dist/finnhub-mcp-server.mcpb && bun run scripts/clean-mcpb.ts dist/finnhub-mcp-server.mcpb",
34
+ "changelog:build": "bun run scripts/build-changelog.ts",
35
+ "changelog:check": "bun run scripts/build-changelog.ts --check",
36
+ "release:github": "bun run scripts/release-github.ts",
37
+ "publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish",
38
+ "test": "vitest run",
39
+ "start": "node dist/index.js",
40
+ "start:stdio": "MCP_TRANSPORT_TYPE=stdio node dist/index.js",
41
+ "start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js"
42
+ },
43
+ "keywords": [
44
+ "mcp",
45
+ "mcp-server",
46
+ "model-context-protocol",
47
+ "typescript",
48
+ "bun",
49
+ "stdio",
50
+ "streamable-http",
51
+ "finnhub",
52
+ "finance",
53
+ "stocks",
54
+ "market-data",
55
+ "quotes",
56
+ "earnings",
57
+ "stock-market"
58
+ ],
59
+ "repository": {
60
+ "type": "git",
61
+ "url": "git+https://github.com/cyanheads/finnhub-mcp-server.git"
62
+ },
63
+ "license": "Apache-2.0",
64
+ "engines": {
65
+ "bun": ">=1.3.0",
66
+ "node": ">=24.0.0"
67
+ },
68
+ "publishConfig": {
69
+ "access": "public"
70
+ },
71
+ "dependencies": {
72
+ "@cyanheads/mcp-ts-core": "^0.10.6",
73
+ "pino-pretty": "^13.1.3",
74
+ "zod": "^4.4.3"
75
+ },
76
+ "devDependencies": {
77
+ "@biomejs/biome": "2.5.0",
78
+ "@types/node": "25.9.3",
79
+ "depcheck": "^1.4.7",
80
+ "ignore": "^7.0.5",
81
+ "tsc-alias": "^1.8.17",
82
+ "typescript": "^6.0.3",
83
+ "vitest": "^4.1.8"
84
+ }
85
+ }
package/server.json ADDED
@@ -0,0 +1,125 @@
1
+ {
2
+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
3
+ "name": "io.github.cyanheads/finnhub-mcp-server",
4
+ "description": "Real-time US-equity quotes, company fundamentals, earnings, analyst trends, and news via Finnhub.",
5
+ "repository": {
6
+ "url": "https://github.com/cyanheads/finnhub-mcp-server",
7
+ "source": "github"
8
+ },
9
+ "version": "0.1.0",
10
+ "packages": [
11
+ {
12
+ "registryType": "npm",
13
+ "registryBaseUrl": "https://registry.npmjs.org",
14
+ "identifier": "@cyanheads/finnhub-mcp-server",
15
+ "runtimeHint": "node",
16
+ "version": "0.1.0",
17
+ "packageArguments": [
18
+ {
19
+ "type": "positional",
20
+ "value": "run"
21
+ },
22
+ {
23
+ "type": "positional",
24
+ "value": "start:stdio"
25
+ }
26
+ ],
27
+ "environmentVariables": [
28
+ {
29
+ "name": "FINNHUB_API_KEY",
30
+ "description": "Required. Free Finnhub API key from https://finnhub.io/register (Dashboard → API key). Free tier: 60 req/min, US real-time.",
31
+ "format": "string",
32
+ "isRequired": true
33
+ },
34
+ {
35
+ "name": "FINNHUB_BASE_URL",
36
+ "description": "Override the Finnhub REST API base URL (local testing / proxy).",
37
+ "format": "string",
38
+ "isRequired": false,
39
+ "default": "https://finnhub.io/api/v1"
40
+ },
41
+ {
42
+ "name": "MCP_LOG_LEVEL",
43
+ "description": "Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').",
44
+ "format": "string",
45
+ "isRequired": false,
46
+ "default": "info"
47
+ }
48
+ ],
49
+ "transport": {
50
+ "type": "stdio"
51
+ }
52
+ },
53
+ {
54
+ "registryType": "npm",
55
+ "registryBaseUrl": "https://registry.npmjs.org",
56
+ "identifier": "@cyanheads/finnhub-mcp-server",
57
+ "runtimeHint": "node",
58
+ "version": "0.1.0",
59
+ "packageArguments": [
60
+ {
61
+ "type": "positional",
62
+ "value": "run"
63
+ },
64
+ {
65
+ "type": "positional",
66
+ "value": "start:http"
67
+ }
68
+ ],
69
+ "environmentVariables": [
70
+ {
71
+ "name": "FINNHUB_API_KEY",
72
+ "description": "Required. Free Finnhub API key from https://finnhub.io/register (Dashboard → API key). Free tier: 60 req/min, US real-time.",
73
+ "format": "string",
74
+ "isRequired": true
75
+ },
76
+ {
77
+ "name": "FINNHUB_BASE_URL",
78
+ "description": "Override the Finnhub REST API base URL (local testing / proxy).",
79
+ "format": "string",
80
+ "isRequired": false,
81
+ "default": "https://finnhub.io/api/v1"
82
+ },
83
+ {
84
+ "name": "MCP_HTTP_HOST",
85
+ "description": "The hostname for the HTTP server.",
86
+ "format": "string",
87
+ "isRequired": false,
88
+ "default": "127.0.0.1"
89
+ },
90
+ {
91
+ "name": "MCP_HTTP_PORT",
92
+ "description": "The port to run the HTTP server on.",
93
+ "format": "string",
94
+ "isRequired": false,
95
+ "default": "3010"
96
+ },
97
+ {
98
+ "name": "MCP_HTTP_ENDPOINT_PATH",
99
+ "description": "The endpoint path for the MCP server.",
100
+ "format": "string",
101
+ "isRequired": false,
102
+ "default": "/mcp"
103
+ },
104
+ {
105
+ "name": "MCP_AUTH_MODE",
106
+ "description": "Authentication mode to use: 'none', 'jwt', or 'oauth'.",
107
+ "format": "string",
108
+ "isRequired": false,
109
+ "default": "none"
110
+ },
111
+ {
112
+ "name": "MCP_LOG_LEVEL",
113
+ "description": "Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').",
114
+ "format": "string",
115
+ "isRequired": false,
116
+ "default": "info"
117
+ }
118
+ ],
119
+ "transport": {
120
+ "type": "streamable-http",
121
+ "url": "http://localhost:3010/mcp"
122
+ }
123
+ }
124
+ ]
125
+ }