Skip to main content
Glama
esurovtsev

finance-mcp

by esurovtsev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Finance MCP Server

A minimal MCP server built with Python that exposes two example tools: one to convert a company name into a stock symbol, and another to fetch financial data from Yahoo Finance. The project focuses on learning how to build and run an MCP server—using a simple financial scenario purely as a demo use case.

Installation

Development Installation

# Clone the repository
git clone https://github.com/yourusername/mcp-finance-server-py.git
cd mcp-finance-server-py

# Install in development mode
uv pip install -e .

Production Installation

uv pip install finance-mcp

Related MCP server: Model Context Protocol Demo

Usage

Running the Server Directly

finance-mcp

Configuration with Claude Desktop or other MCP clients

Add this to your MCP configuration file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "finance-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-finance-server-py", // Update this path
        "run",
        "finance-mcp"
      ]
    }
  }
}

Video Walkthrough

Build Your Own MCP Server: Practical Guide with Python SDK and Cursor IDE

Watch: Build Your Own MCP Server: Practical Guide with Python SDK and Cursor IDE

This video provides context and explanations that complement the code in this repository:

  • See the MCP server in action with a practical demonstration in Cursor IDE

  • Understand the design decisions behind the implementation

  • Learn how the different components work together

  • Get insights into how AI models discover and interact with custom tools

If you're looking to understand not just the "what" but the "why" behind this MCP implementation, the video offers a guided tour through the development process and explains the reasoning behind key architectural choices.

Available Tools

2 tools
fetch_stock_dataC

Fetches comprehensive stock data for a given symbol.

Args: stock_symbol: The stock ticker symbol (e.g., 'TSLA'). period: The period to analyze (e.g., '1mo', '3mo', '1y').

Returns: A dictionary combining general stock info and historical market data.

ParametersJSON Schema
NameRequiredDescriptionDefault
periodNo1mo
stock_symbolYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must carry full burden. Mentions return type (dictionary with stock info and historical data) but lacks details on data freshness, rate limits, or idempotency. Not enough to fully inform an agent about behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description uses a docstring format with Args and Returns sections, which is structured but slightly verbose. Could be more concise without the formal sections.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, so description should detail return value structure. Only says 'dictionary combining general stock info and historical market data,' which is vague. Lacks error handling or edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description adds meaning: 'stock_symbol' as ticker symbol with example 'TSLA', 'period' as analysis period with examples. Provides default for period. Lacks allowed values for period, but is adequate for basic usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Fetches comprehensive stock data for a given symbol.' The verb 'Fetches' and resource 'stock data' are specific. Differentiates from sibling 'lookup_stock_symbol' by implication, but could be more explicit about the scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus the sibling 'lookup_stock_symbol'. Missing prerequisites or context for appropriate usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lookup_stock_symbolB

Converts a company name to its stock symbol using a financial API.

Args: company_name: The full company name (e.g., 'Tesla').

Returns: The stock symbol (e.g., 'TSLA') or an error message.

ParametersJSON Schema
NameRequiredDescriptionDefault
company_nameYes

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It mentions using a financial API and returns symbol or error, but does not disclose rate limits, authentication needs, or idempotency. Basic transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences including Args and Returns. No extraneous text. Highly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Simple tool with one parameter and no output schema. Description adequately explains purpose and return. Could mention expected company name format (e.g., full legal name), but not necessary for basic use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

One parameter, company_name, is described with example 'Tesla'. Schema coverage is 0% but description effectively provides 100% coverage. Adds an example beyond schema, which is helpful but minimal. Baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool converts a company name to a stock symbol using a financial API. It distinguishes from sibling 'fetch_stock_data' which likely fetches data for a given symbol.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. Sibling tool is named but no differentiation or context provided. Agent has no help in deciding which to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedfetch_stock_data
    • First observedlookup_stock_symbol
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 2 tools

Disambiguation5/5

Each tool serves a distinct purpose: one converts company names to stock symbols, the other fetches stock data given a symbol. No overlap in functionality.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with snake_case: 'fetch_stock_data' and 'lookup_stock_symbol', making them predictable and easy to understand.

Tool Count3/5

With only 2 tools, the set feels thin for a finance server. While the two tools are essential, the count is borderline low, lacking additional common operations.

Completeness2/5

The server covers only basic stock data retrieval and symbol lookup. Many common finance operations (e.g., financial statements, market indices, historical comparisons) are missing, posing significant gaps for agents.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Yahoo Finance MCP Server

    narumiruna
    A
    license
    A
    quality
    A
    maintenance
    A simple MCP server for Yahoo Finance using yfinance. This server provides a set of tools to fetch stock data, news, and other financial information.
    15
    191
    MIT

  • Model Context Protocol Demo

    digital-duck
    A
    license
    Not graded
    quality
    D
    maintenance
    A demonstration server for the Model Context Protocol (MCP) that exposes calculator and Yahoo Finance tools, allowing LLMs to interpret natural language requests and make tool calls via the MCP standard.
    1
    Apache 2.0

  • Yahoo Finance MCP Server

    benethos-hub
    A
    license
    A
    quality
    A
    maintenance
    MCP server that exposes Yahoo Finance data through tools for searching instruments, fetching quotes, history, company info, financials, dividends, news, recommendations, and options. Enables AI assistants to answer market-data questions using natural language.
    22
    MIT