Alchemy Blockchain Data Gateway (MCP Server)

A specialized Model Context Protocol (MCP) intermediary facilitating structured access for AI entities to the extensive suite of Alchemy's decentralized ledger APIs. This architecture permits agents to solicit blockchain insights directly, circumventing the need for imperative code generation.

Primary Operational Capabilities

This MCP service establishes a controlled pathway between autonomous agents and Alchemy's data retrieval endpoints, empowering agents to perform the following operations:

• Determine asset valuations and retrieve historical pricing trajectories (supporting granular temporal scope queries).
• Access comprehensive digital collectible (NFT) possession data and associated contract metadata.
• Audit the history of on-chain activities across disparate ledger environments.
• Ascertain token balances held across a multi-chain topology.
• Obtain granular records of asset transfers, complete with advanced filtering mechanisms.
• Dispatch ledger mutations via Smart Contract Accounts (Prerequisite: Operational wallet agent service required).
• Orchestrate automated token exchanges utilizing Decentralized Exchange (DEX) protocols (Prerequisite: Operational wallet agent service required).
• And further advanced capabilities...

Expedited Deployment Procedure

To rapidly integrate this MCP gateway, integrate the subsequent configuration block into your primary MCP configuration manifest (often located within your execution environment's settings):

{ "mcpServers": { "alchemy": { "command": "npx", "args": [ "-y", "@alchemy/mcp-server" ], "env": { "ALCHEMY_API_KEY": "YOUR_API_KEY" } } } }

This setup facilitates immediate server invocation without local repository cloning.

Required Environment Configuration

The gateway mandates the following environmental parameters for initial function:

• ALCHEMY_API_KEY - The credential key furnished by Alchemy (essential for all data queries).

For Mutation and Exchange Functionality, the following must also be declared:

• AGENT_WALLET_SERVER - The network address pointing to an active wallet agent service responsible for Secure Contract Account operations.

⚠️ Critical Notice: The sendTransaction and swap functionalities remain inaccessible unless a correctly provisioned wallet agent service is referenced via AGENT_WALLET_SERVER. These functions necessitate external cryptographic infrastructure for signature generation and transaction broadcasting.

Accessible Service Endpoints

Agents can be instructed to utilize the following methods:

Valuation Retrieval Endpoints

1. fetchTokenPriceBySymbol
2. Fetches contemporary price metrics based on asset ticker symbol.

3. Illustration: "What is the present valuation of ETH and BTC?"

4. fetchTokenPriceByAddress

5. Retrieves real-time valuation data using the asset's contract identifier.

6. Illustration: "What is the price of the asset at contract 0x1234...5678 on the Ethereum mainnet?"

7. fetchTokenPriceHistoryBySymbol

8. Obtains chronological pricing data for symbols over defined temporal windows.

9. Illustration: "Display BTC price trajectory from January 1st to February 1st, 2023, aggregated daily."

10. fetchTokenPriceHistoryByTimeFrame

11. Retrieves historical pricing utilizing flexible temporal definitions or natural language inputs.
12. Illustration: "Derive ETH pricing data for the preceding seven days" or "Acquire BTC valuation over the last month."

Multi-Chain Asset Query Endpoints

1. fetchTokensOwnedByMultichainAddresses
2. Gathers asset holdings reports for specified accounts across numerous ledgers.
3. Illustration: "Enumerate the tokens held by address 0xabc...123 on Ethereum and the Base network?"

Transaction Audit Endpoints

1. fetchAddressTransactionHistory
2. Retrieves the recorded sequence of activities for an account spanning multiple networks.

3. Illustration: "List recent ledger entries for wallet 0xdef...456 on Ethereum."

4. fetchTransfers

5. Yields granular data concerning asset movements, supporting sophisticated filtering criteria.
6. Illustration: "Report all ERC-20 asset movements originating from or destined for 0xghi...789."

Digital Collectible (NFT) Endpoints

1. fetchNftsOwnedByMultichainAddresses
2. Secures a complete inventory of owned NFTs, including anti-spam filtration logic.

3. Illustration: "Which NFTs are possessed by 0xjkl...012?"

4. fetchNftContractDataByMultichainAddress

5. Retrieves metadata pertaining to NFT contract registrations associated with specific addresses.
6. Illustration: "What NFT collection metadata is associated with address 0xmno...345?"

Transaction Dispatch Endpoints

1. sendTransaction
   • Executes outgoing transactions through Secure Contract Accounts.
   • ⚠️ Crucial: Mandates a functional wallet agent service accessible via AGENT_WALLET_SERVER.
   • Illustration: "Transfer a value of 0.1 ETH to recipient 0xpqr...678."

Exchange Orchestration Endpoints

1. swap
   • Initiates automated token exchanges leveraging established DEX infrastructures (e.g., Uniswap).
   • ⚠️ Crucial: Requires a properly configured wallet agent service linked via AGENT_WALLET_SERVER.
   • Illustration: "Execute an exchange: 100 USDC converted to ETH."

Local Development and Community Contribution Guidelines

Initial Acquisition

1. Fork the source repository structure. bash git clone https://github.com/alchemyplatform/alchemy-mcp.git cd alchemy-mcp

2. Install prerequisite dependencies. bash pnpm install

Development Mode

bash pnpm watch

Production Build Generation

bash pnpm build

Utilizing the MCP Inspector for Diagnostics

The MCP Inspector provides a graphical utility for scrutinizing and validating the server's operational status:

bash pnpm inspector

Launching this command starts the visual testing environment, accessible via a web browser, enabling users to: - Catalog all accessible service methods. - Test methods with varied input parameters. - Inspect the returned data payloads. - Trace and resolve server-side operational anomalies.

Collaboration Policy

Contribution via pull requests is highly encouraged. For substantial architectural adjustments, please initiate a discussion by opening an issue prior to submitting modifications.

Licensing Framework

This MCP gateway is distributed under the permissive MIT License. This grants broad freedom to utilize, adapt, and redistribute the software, provided the stipulated terms of the MIT License are observed.

Illustrative Agent Queries

These examples demonstrate prompts suitable for agent interaction:

Determine the present market rates for Bitcoin and Ethereum.

Retrieve the catalog of NFTs held by address 0x1234...5678 on the Ethereum ledger.

What assets are currently possessed by wallet 0xabcd...6789 across the Ethereum and Base chains?

Furnish the complete transaction history for 0x9876...5432.

Provide the valuation data for Ethereum from January 1st until the present day, aggregated on a daily frequency.

Obtain BTC price information for the recent seven-day period, sampled hourly.

Chart the recent month's price performance for ETH.

List all ERC-20 asset movements involving address 0x1234...5678 within the last 100 recorded blocks?

Underlying API Reference

For exhaustive technical specifications regarding Alchemy's data interfaces, consult: - Alchemy API Documentation