Local MCP Server

Overview

This guide provides comprehensive documentation for running the Kensho LLM-Ready API MCP (Model Context Protocol) (opens in a new tab) server locally. The MCP server exposes kFinance tools through the Model Context Protocol, supporting multiple authentication methods and transport protocols to accommodate different deployment scenarios.

For remote hosting options, please refer to our Remote MCP Server integrations.

Installation

Python Installation

For users who do not already have Python>=3.10 installed, please follow instructions here (opens in a new tab) to get set up.

kFinance Library Installation

Installation instructions are provided in the kFinance GitHub repository (opens in a new tab), but for clarity they are reproduced here.

To install the library, run:

pip install kensho-kfinance

Then confirm in the output that the installation completed successfully.

Quick Start: Claude Desktop Integration

Below are the basic steps required to add the LLM-Ready API MCP server to Claude Desktop (opens in a new tab). More detailed information can be found on the official MCP documentation (opens in a new tab).

Open Claude Desktop.
Navigate to the Settings panel.
In the "Developer" tab, click "Edit Config".
Open claude_desktop_config.json in a text editor like Notepad or TextEdit.
Paste the following settings into the config, replacing <path_to_python> below with your appropriate path.

{
  "mcpServers": {
    "kfinance": {
      "command": "<path_to_python>",
        "args": [
          "-m",
          "kfinance.mcp",
          "--stdio"
        ]
     }
   }
}

Exit and restart Claude Desktop.

CLI Reference

Running the MCP Server

To initialize and start the MCP server, use the following command:

python -m kfinance.mcp

This command starts the MCP server with default settings. You can customize the server behavior using the command-line arguments detailed below.

Command Signature

The full command signature with all available options:

python -m kfinance.mcp [--stdio|-s] [--sse] --refresh-token <refresh-token> --client-id <client-id> --private-key <private-key>

Authentication Methods

The MCP server supports three authentication methods, evaluated in the following order of precedence:

1. Refresh Token Authentication

Refresh tokens expire after 7 days. This method is not advisable for use in production workflows.

Uses an existing refresh token for authentication. This method is ideal for development, testing, or temporary deployments.

Usage:

python -m kfinance.mcp --refresh-token <refresh-token>

Arguments:

--refresh-token <refresh-token> — Your refresh token obtained from kfinance.kensho.com/manual_login (opens in a new tab)

When to Use:

Quick experiments and prototyping
Development and testing environments
Short-term batch jobs

When NOT to Use:

Production environments
Automated workflows that need to run beyond 7 days

Learn More: Refresh Token Authentication Guide

2. Key Pair Authentication

Uses client ID and private key for authentication. This method is recommended for production deployments requiring server-to-server authentication.

Usage:

python -m kfinance.mcp --client-id <client-id> --private-key <private-key>

Arguments:

--client-id <client-id> — Your OAuth client ID
--private-key <private-key> — Your private key

When to Use:

Production environments
Automated deployments
Server-to-server authentication scenarios

Learn More: OAuth Client Credentials Flow Guide

3. Browser-Based Authentication

Falls back to browser-based authentication if no authentication arguments are provided. This method launches an interactive OAuth flow in your default browser.

Usage:

python -m kfinance.mcp

When to Use:

First-time setup
Interactive development
Environments with browser access

Transport Layers

The MCP server supports two transport protocols for communicating with MCP clients:

Standard I/O (stdio)

Standard input/output transport, commonly used for local integrations like Claude Desktop.

Usage:

python -m kfinance.mcp --stdio
# or
python -m kfinance.mcp -s

Arguments:

--stdio or -s — Enable stdio transport

When to Use:

Local MCP client integrations
Claude Desktop and similar applications
Direct process communication

Server-Sent Events (SSE)

HTTP-based transport using Server-Sent Events, suitable for web-based integrations.

Usage:

python -m kfinance.mcp --sse
# or
python -m kfinance.mcp

Arguments:

--sse — Enable SSE transport (also the default when no transport flag is specified)

When to Use:

Web-based integrations
Remote MCP client connections
HTTP-compatible environments