Add CLI and config file support

[nbarraud]

Motivation and Context

This PR adds two major features to the MCP Inspector:

1. CLI Mode: The CLI provides a scriptable alternative to the web client for inspecting MCP servers. It supports programmatic interaction, making it useful for tasks like running test scripts or integrating with coding assistants like Cursor. Example usage:

npx @modelcontextprotocol/inspector node build/index.js --cli --method tools/call --tool-name mytool --tool-arg key=value --tool-arg another=value2

2. Configuration File Support: Allows storing settings for different MCP servers in a JSON configuration file, making it easier to work with multiple servers or complex configurations without having to remember and type long command lines. This configuration approach aligns with how Claude Desktop and most other MCP tools configure MCP servers, providing a consistent experience across the MCP ecosystem.

How Has This Been Tested?

The implementation has been tested with various MCP servers, including local and remote servers. Test scenarios include:

• Basic CLI operations for tools, resources, and prompts
• Configuration file loading with different server configurations
• Error handling for invalid inputs and configurations
• Integration with existing inspector functionality

Shell-based tests have been added in bin/tests/cli-tests.sh to verify the functionality.

Breaking Changes

No breaking changes. All existing functionality continues to work as before. The new features are opt-in through the --cli flag for CLI mode and the --config/--server flags for configuration file support.

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

The implementation consists of two main components:

1. A CLI module (cli/) that handles the programmatic interaction with MCP servers
2. Updates to the bin module (bin/) to support configuration files and CLI mode

To support the more complex logic required for these features, the bin/ directory has been converted into a TypeScript project.

[seuros]

I believe the CLI console should be integrated into the web console.

Essentially, this involve merging another tool into the inspector, but it could also work well as a standalone tool.

[nbarraud]

I believe the CLI console should be integrated into the web console.

Essentially, this involve merging another tool into the inspector, but it could also work well as a standalone tool.

The CLI client is meant to exist as an alternative UI from the web client. It can't live within a web client by its very nature.

It allows inspecting MCP servers via the command line rather than via a web interface. The goal is to facilitate programmatic access to MCP servers. For example running test scripts to validate an MCP server, or as a feedback loop when using coding assistant like Cursor, so the assistant can autonomously test MCP servers during development.

[seuros]

Oh , perfect, i just saw you added the inspector-bin package.

[olaservo]

To my understanding the enhanced cli mode would support a subset of the UI-based testing features, correct? Do you think there should be some kind of feature breakdown table to make it clearer what the 'cli-mode' can be used to test, vs the UI mode, or should this be self-evident?

Thinking through what would still require the UI:

• approving or rejecting sampling requests
• other interactive enhancements like the ability to subscribe or unsubscribe to specific resources

Since the main purpose of this new cli mode seems to be streamlining testing MCP server functionality rather than simulating the expected user interactions, maybe this is a non issue, as long as that "when to use what mode" is clear to the user.

[nbarraud]

To my understanding the enhanced cli mode would support a subset of the UI-based testing features, correct? Do you think there should be some kind of feature breakdown table to make it clearer what the 'cli-mode' can be used to test, vs the UI mode, or should this be self-evident?

Thinking through what would still require the UI:

• approving or rejecting sampling requests
• other interactive enhancements like the ability to subscribe or unsubscribe to specific resources

Since the main purpose of this new cli mode seems to be streamlining testing MCP server functionality rather than simulating the expected user interactions, maybe this is a non issue, as long as that "when to use what mode" is clear to the user.

Yes it's a one shot call to any MCP server, so some round-tripping functionalities are not supported at the moment, although they could, I think.

Goal is to get the output of the MCP server on stdout so anyone or anything can read it and react accordingly. Personally I need it as part of automated testing workflows and using coding agents while developing MCP servers, where it's very useful to create a feedback loop between the agent and the output.

I'm happy to add that table/explanation in the README if you would like me to.

[olaservo]

Hi @nbarraud, just wanted to let you know I'm not ignoring this one, since its a significant update I am pinging a few people directly for more eyes on it. :)

[olaservo]

Overall this looks good to me, although so far I noticed a few things that are not cooperating on Windows. I am still tinkering with the script setup on my Windows machine, but I didn't want to leave you hanging and don't see anybody else weighing in yet. Will ping a couple others again to make sure there aren't any showstoppers here I am missing.

[olaservo]

Something to note once this is about to be merged - looks like some sections were accidentally deleted from Readme.

[nbarraud]

I fixed that and added a table as you requested earlier.

[olaservo]

I got a little stuck on trying to run these tests myself on my Windows machine using Git Bash. Still investigating but it seems like the script hangs when connecting using npx plus it does not terminate even when I change the commands to use node and a local server file. Probably not specific to this script and more my own environment.

[nbarraud]

I converted the tests to .js so it can be run on all systems (in theory)... Give it a try.

[olaservo]

Lets make this Windows compatible using something like:
"postbuild": "node -e \"const fs=require('fs'); fs.copyFileSync('build/index.js', 'cli.js'); if(process.platform !== 'win32') require('child_process').execSync('chmod +x build/index.js')\""

[nbarraud]

Done.

[nbarraud]

Thank you for reviewing @olaservo

I will rebase to take into accounts later PRs and changes to the README. I don't have Windows at the moment so I will have to defer to you on that part. I can apply your suggested changes for Windows compat but won't be able to test it easily.

[nbarraud]

Thank you for your comments @pulkitsharma07

Very busy on other projects this week but I will answer soon.

[pulkitsharma07]

@nbarraud @olaservo feel free to ignore my comments, I guess most of them can be done in a separate PR as an improvement.

[nbarraud]

Hey @olaservo, just checking in!

[olaservo]

Hi @nbarraud just catching up from being offline a little while. I approved this and we can get these enhancements merged in once you get a chance to resolve the latest conflicts. I will keep an eye out just in case the changes to resolve conflicts revoke the approval. Thanks!

[nbarraud]

Hi @nbarraud just catching up from being offline a little while. I approved this and we can get these enhancements merged in once you get a chance to resolve the latest conflicts. I will keep an eye out just in case the changes to resolve conflicts revoke the approval. Thanks!

Thank you @olaservo, I resolved the conflicts and the PR is ready for merging! I guess that revoked the approval...

EDIT: I don't know if I'm supposed to increment the version number or if this is the responsibility of the maintainers. Let me know.

[nbarraud]

New conflicts popped up over the weekend so I resolved them. @olaservo please approve, thank you!

[olaservo]

Re-approving after conflict resolutions.

[olaservo]

Hi @nbarraud just catching up from being offline a little while. I approved this and we can get these enhancements merged in once you get a chance to resolve the latest conflicts. I will keep an eye out just in case the changes to resolve conflicts revoke the approval. Thanks!

Thank you @olaservo, I resolved the conflicts and the PR is ready for merging! I guess that revoked the approval...

EDIT: I don't know if I'm supposed to increment the version number or if this is the responsibility of the maintainers. Let me know.

Maintainers bump the version separately when preparing a release.

[nbarraud]

Re-approving after conflict resolutions.

Thank you @olaservo, I think the workflow still needs approval?

[cliffhall]

LGTM! 👍
Tests run locally.